Attachments & URL Context

Upload files, attach URLs, list/download attachments, and remove attachment context for debates.

3 min read
Share

Attachments let you provide source documents to a debate. AskVerdict extracts text and uses it as context for agent reasoning.

Scope and ownership

All attachment routes are scoped to your own debates under /api/debates/*. You cannot access attachments for debates you do not own.

Supported file types and limits

CapabilityDefault
Supported file types.pdf, .txt, .md, .docx
Max file size10 MB per file
Max attachments per debate5
Max extracted context50,000 characters per attachment

Asynchronous extraction

File upload returns immediately after storage. Text extraction and chunk processing run asynchronously in the background.

POST /api/debates/:id/attachments

POST/api/debates/:id/attachments

Upload a file attachment to a debate using multipart/form-data.

Path Parameters

NameTypeRequiredDescription
idstring (UUID)RequiredDebate ID.

Form Data

NameTypeRequiredDescription
fileFileRequiredAttachment file. Allowed extensions: .pdf, .txt, .md, .docx.

Example Request

bash
curl -X POST https://api.askverdict.ai/api/debates/550e8400-e29b-41d4-a716-446655440000/attachments \
  -H "Authorization: Bearer vrd_your_api_key" \
  -F "file=@./decision-memo.pdf"

Response

Error Responses

StatusCodeDescription
400VALIDATION_ERRORInvalid multipart body, unsupported extension, size limit, or attachment cap
401UNAUTHORIZEDMissing or invalid authentication
404NOT_FOUNDDebate not found or not owned by user
500INTERNAL_ERRORUpload/storage failure

GET /api/debates/:id/attachments

GET/api/debates/:id/attachments

List all attachments currently associated with a debate.

Example Request

bash
curl https://api.askverdict.ai/api/debates/550e8400-e29b-41d4-a716-446655440000/attachments \
  -H "Authorization: Bearer vrd_your_api_key"

Response

GET /api/debates/:id/attachments/:attachmentId/download

GET/api/debates/:id/attachments/:attachmentId/download

Download an uploaded file attachment. URL attachments return the original URL payload.

Behavior

  • Binary attachments return streamed content with Content-Disposition: attachment.
  • URL attachments (created via fetch-url) return JSON: { "url": "https://..." }.

Example Request

bash
curl -L https://api.askverdict.ai/api/debates/550e8400-e29b-41d4-a716-446655440000/attachments/att_9f2f0f6a/download \
  -H "Authorization: Bearer vrd_your_api_key" \
  -o decision-memo.pdf

DELETE /api/debates/:id/attachments/:attachmentId

DELETE/api/debates/:id/attachments/:attachmentId

Delete an attachment from a debate.

Response

Error Responses

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid auth
403FORBIDDENAttachment exists but is not owned by caller
404NOT_FOUNDAttachment not found

POST /api/debates/fetch-url

POST/api/debates/fetch-url

Fetch a web page server-side, extract readable text, and store it as a URL attachment.

Request Body

NameTypeRequiredDescription
debateIdstring (UUID)RequiredDebate ID to attach URL context to.
urlstring (http/https URL)RequiredPublic URL to fetch and extract into debate context.

Example Request

bash
curl -X POST https://api.askverdict.ai/api/debates/fetch-url \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "debateId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/market-report"
  }'

Response

Was this page helpful?

PreviousHealth ChecksNextSharing & Public Debate Access