Skip to main content
POST
/
v1
/
portal
/
match
curl -X POST https://portal-api.7331.org/v1/portal/match \
  -H "Content-Type: application/json" \
  -b "psession=YOUR_SESSION" \
  -d '{"interests": ["gaming", "music"]}'

{
  "state": "searching",
  "interests": ["gaming", "music"],
  "expires_at": "2026-05-06T18:00:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.7331.org/llms.txt

Use this file to discover all available pages before exploring further.

Adds the authenticated user (registered or stranger) to the matchmaking queue on the given interest tags. Returns immediately with the searching state so the frontend can start polling GET /v1/portal/match/status.
​
interests
string[]
required
One to three interest tags (e.g. ["gaming", "music"]). Each tag must be 3–12 lowercase alphanumeric characters matching ^[a-z0-9]{3,12}$. The user is placed into all listed queues simultaneously — the first pair-match on any shared tag wins.

​
Response

​
state
string
required
One of idle, searching, matched.
​
interests
string[]
Interest tags the user is currently queued on — populated when state is searching.
​
token
string
Match token — populated when state is matched. Pass this to the socket join or use it to navigate to the direct chat.
​
expires_at
string
ISO-8601 timestamp — populated when state is searching (queue TTL deadline) or matched (24h chat expiry). The client must re-enqueue before this time or the server reaps the entry.

​
Errors

StatusErrorMeaning
400ERR_MATCH_UNSUPPORTED_INTERESTA tag fails validation — must be 3–12 lowercase alphanumeric characters
403ERR_STRANGER_BLOCKEDStranger session has been blocked by a moderator
409ERR_MATCH_ALREADY_SEARCHINGAlready in a queue
409ERR_MATCH_SLOT_LIMITConcurrent active direct chat limit reached (1 for free accounts, 3 for premium)
curl -X POST https://portal-api.7331.org/v1/portal/match \
  -H "Content-Type: application/json" \
  -b "psession=YOUR_SESSION" \
  -d '{"interests": ["gaming", "music"]}'

{
  "state": "searching",
  "interests": ["gaming", "music"],
  "expires_at": "2026-05-06T18:00:00Z"
}