Sharing & Public Debate Access

Create share links, update visibility settings, revoke links, and retrieve public debates by token.

2 min read
Share

These endpoints let owners publish debates with share tokens and let external consumers fetch public debate data for embeds and replay.

Authenticated sharing endpoints

All /api/share/* routes require auth and ownership of the target debate.

MethodPathDescription
POST/api/share/:debateIdGenerate or rotate a share token
PATCH/api/share/:debateIdUpdate share settings
DELETE/api/share/:debateIdRevoke sharing and invalidate token

POST /api/share/:debateId

POST/api/share/:debateId

Create a public share token and URL for a debate.

Response

Share URL vs API URL

shareUrl is a frontend page URL for humans. For programmatic access, use GET /api/public/debates/:token.

PATCH /api/share/:debateId

PATCH/api/share/:debateId

Update sharing controls for comments, forking, and visibility options.

Request Body

NameTypeRequiredDescription
settings.allowCommentsbooleanOptionalAllow comments on the shared debate.
settings.allowForkbooleanOptionalAllow others to fork the debate.
settings.showCostbooleanOptionalExpose result cost metadata in public payloads.
settings.requireSignInbooleanOptionalRequire authenticated session to view shared debate UI.

Example Request

bash
curl -X PATCH https://api.askverdict.ai/api/share/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "allowComments": true,
      "allowFork": false,
      "showCost": false,
      "requireSignIn": false
    }
  }'

Response

DELETE /api/share/:debateId

DELETE/api/share/:debateId

Disable sharing and remove the active share token for a debate.

Response

Public embed endpoint

GET /api/public/debates/:token is unauthenticated and CORS-enabled for embed use cases.

GET/api/public/debates/:token

Fetch sanitized public debate payload plus ordered replay events by share token.

Example Request

bash
curl https://api.askverdict.ai/api/public/debates/6ebfc20f-39f8-4ee3-b1a0-4be0fbe3bb84

Response

CORS and preflight

  • GET /api/public/debates/:token returns:
    • Access-Control-Allow-Origin: *
    • Access-Control-Allow-Methods: GET, OPTIONS
    • Access-Control-Allow-Headers: Content-Type
  • OPTIONS /api/public/debates/:token returns 204.

Rate limiting

Public token endpoint is IP rate-limited (sliding window). Defaults:

  • 30 requests
  • per 60 seconds
  • Retry-After header on 429

Error Responses

StatusCodeDescription
400VALIDATION_ERRORInvalid PATCH body schema
401UNAUTHORIZEDMissing/invalid auth for /api/share/*
404NOT_FOUNDDebate or token not found
429RATE_LIMITEDPublic token endpoint rate limited

Was this page helpful?

PreviousAttachments & URL ContextNextSDK Installation