API documentation

Create voice and text rooms from your app, then share the link.

Get API key

Agent instructions

Read the Markdown API reference or llms.txt before integrating.

Use POST /rooms with an operator-provided, server-side API key. Browser connection and moderation endpoints are internal.
Share url with guests. Keep hostUrl private for the intended host; do not claim it or join a room unless asked.
Handle error.code, respect Retry-After, and do not automatically retry a timed-out creation request.
Keep API keys and sign-in links out of browser code, shared URLs, and logs.

Create a room

POSThttps://api.poof.vc/rooms

Creates a room for up to five people. Rooms expire 24 hours after creation. You don’t need to choose a host first.

Headers

Authorizationstringrequired: Your API key, sent as Bearer poof_…. Keep it on your server.
Content-Typestringrequired: Must be application/json.

Body parameters

Send a JSON object, up to 4,096 bytes. Use {} for no parameters. Unknown fields are rejected.

nicknamestringoptional: Pre-fills the nickname on the join screen; the user can edit it. Maximum 24 characters after trimming whitespace. An empty string is omitted. The nickname is included in the returned links.

Request

curl https://api.poof.vc/rooms \
  -H "Authorization: Bearer $POOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"blue_mcgoo"}'

Response

Returns 201 Created with a JSON object. All four fields are always present.

codestring: The six-character room code users can enter to join.
urlstring · URI: The room link to share with guests. Includes the nickname if provided.
hostUrlstring · URI: A private, one-time host link. The person who clicks Join room through this link claims lock and remove controls. Opening the link alone doesn’t claim it. Share this with only the intended host; the room also works without a host.
expiresAtstring · date-time: When the room expires, in UTC ISO 8601 format. This is 24 hours after creation.

201Room created

{
  "code": "ABC234",
  "url": "https://poof.vc/r/ABC234?nickname=blue_mcgoo",
  "hostUrl": "https://poof.vc/r/ABC234?nickname=blue_mcgoo#host=…",
  "expiresAt": "2026-10-08T12:00:00.000Z"
}

Errors

Failed requests return a non-2xx status and an error object. Use the code in your application and the message to understand what went wrong.

error.codestring

A stable error code from the list below.

error.messagestring

A description of the problem.

error.requestIdstring

The request’s identifier. Also returned in the X-Request-Id header, including on successful requests.

error.detailsobject[]optional

Field-level information for validation errors.

Field error properties

fieldstring: The field name, or body for the whole request.
codestring: too_long, invalid_value, or unknown_field.
messagestring: A description of the field’s validation problem.

400Validation error

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [{
      "field": "nickname",
      "code": "too_long",
      "message": "Nickname must be 24 characters or fewer."
    }],
    "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.

Retrying requests Each successful request creates a new room. A timeout or lost response can still mean a room was created; don’t automatically retry an uncertain result.

Rate limits

The default limit is 10 requests per minute per developer, shared across all your API keys. Requests that fail body validation also use this quota.

A 429 response includes Retry-After: the number of seconds to wait. Rejected requests don’t extend the window. A separate IP limit also applies.

Response headers

Account quota headers appear after your key and account are verified and the quota is checked.

X-RateLimit-Limitinteger: Your account’s request allowance for the minute.
X-RateLimit-Remaininginteger: Requests left in the current window.
X-RateLimit-Resetinteger: When the window resets, as a Unix timestamp in seconds.
Retry-Afterinteger: Seconds to wait before retrying after a 429.