API documentation
Create a room. Share a link or embed it.
Create a room
POST
https://api.poof.vc/roomsRooms expire after 24 hours.
Headers
Authorizationstringrequired- Send
Bearer poof_…. Keep your API key on your server. Content-Typestringrequiredapplication/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=trueto skip the join screen. The same URL works for all guests. hostEmbedUrlstring · URI- Private host iframe URL. Shares the claim in
hostUrl. Withautojoin=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
| Status | Code | Description |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. Send a JSON object. |
| 400 | validation_error | A field has an invalid value or is not supported. Check error.details. |
| 401 | missing_api_key | Add your API key to the Authorization header. |
| 401 | invalid_api_key | The key is invalid, expired, or revoked. Use an active key. |
| 403 | account_suspended | Developer access has been disabled. |
| 404 | endpoint_not_found | The endpoint does not exist. Check the URL. |
| 405 | method_not_allowed | Use POST. The Allow header lists supported methods. |
| 413 | payload_too_large | The request body exceeds 4,096 bytes. Send a smaller body. |
| 415 | unsupported_media_type | Set Content-Type to application/json. |
| 429 | rate_limit_exceeded | Your account or IP has reached its limit. Wait for Retry-After seconds. |
| 500 | internal_error | An unexpected error occurred. Keep the request ID for troubleshooting. |
| 503 | service_unavailable | A 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.