API documentation

Create a room. Share a link or embed it.

Get API key

Create a room

POSThttps://api.poof.vc/rooms

Rooms expire after 24 hours.

Headers

Authorizationstringrequired
Send Bearer poof_…. Keep your API key on your server.
Content-Typestringrequired
application/json

Body

Send {} for defaults. Maximum 4,096 bytes; unknown fields are rejected.

maxParticipantsintegeroptional · default 5
2–5 people, including the host. Sets the participant counter and admission limit.
Request
curl https://api.poof.vc/rooms \
  -H "Authorization: Bearer $POOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxParticipants":4}'

Response

201 Created. All fields are always present.

codestring
Six-character room code.
urlstring · URI
Guest room link.
hostUrlstring · URI
Private, one-time host link. Grants lock and removal controls on Join.
embedUrlstring · URI
Guest iframe URL. Add autojoin=true to skip the join screen. The same URL works for all guests.
hostEmbedUrlstring · URI
Private host iframe URL. Shares the claim in hostUrl. With autojoin=true, claims host controls when the embed loads.
expiresAtstring · date-time
Expiry in UTC ISO 8601 format.
201Room created
{
  "code": "ABC234",
  "url": "https://poof.vc/r/ABC234",
  "hostUrl": "https://poof.vc/r/ABC234#host=…",
  "embedUrl": "https://poof.vc/r/ABC234/embed",
  "hostEmbedUrl": "https://poof.vc/r/ABC234/embed#host=…",
  "expiresAt": "2026-10-08T12:00:00.000Z"
}

Errors

Non-2xx responses include error.code, message, and requestId. Validation errors also include field-level details.

Keep the request ID for troubleshooting. A timeout may still create a room; don’t automatically retry an uncertain result.

400Validation error
{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [{
      "field": "maxParticipants",
      "code": "invalid_value",
      "message": "Too small: expected number to be >=2"
    }],
    "requestId": "req_…"
  }
}
Error codes
StatusCodeDescription
400invalid_jsonThe body is not valid JSON. Send a JSON object.
400validation_errorA field has an invalid value or is not supported. Check error.details.
401missing_api_keyAdd your API key to the Authorization header.
401invalid_api_keyThe key is invalid, expired, or revoked. Use an active key.
403account_suspendedDeveloper access has been disabled.
404endpoint_not_foundThe endpoint does not exist. Check the URL.
405method_not_allowedUse POST. The Allow header lists supported methods.
413payload_too_largeThe request body exceeds 4,096 bytes. Send a smaller body.
415unsupported_media_typeSet Content-Type to application/json.
429rate_limit_exceededYour account or IP has reached its limit. Wait for Retry-After seconds.
500internal_errorAn unexpected error occurred. Keep the request ID for troubleshooting.
503service_unavailableA required service is temporarily unavailable.

Rate limits

10 requests per minute per developer, shared across keys. Validation failures count. On 429, wait the number of seconds in Retry-After.

Response headers
X-RateLimit-Limitinteger
Requests allowed per minute.
X-RateLimit-Remaininginteger
Requests left in this window.
X-RateLimit-Resetinteger
Window end as Unix seconds.
Retry-Afterinteger
Seconds to wait after a 429.