Skip to main content
POST
/
extractions
/
sessions
/
{sessionId}
/
documents
Upload Document
curl --request POST \
  --url https://api.raydocs.com/extractions/sessions/{sessionId}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filename": "<string>",
  "mime_type": "<string>",
  "size": 123,
  "status": "pending",
  "extraction_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z"
}
This endpoint is Step 3 of a 3-step upload process. Files must first be uploaded to temporary storage via signed URL before being associated with a session. See the complete upload guide for the full flow.

​
How It Works

This endpoint doesn’t receive the file directly—it creates a document record linking a file (already uploaded to S3) with your extraction session.

​
Authentication & Scope

Requires the sessions-write ability.

​
Request

This endpoint expects a JSON body with the file key (from Step 1) and filename—not a binary file upload. 
POST /extractions/sessions/770e8400-e29b-41d4-a716-446655440000/documents HTTP/1.1
Host: api.raydocs.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "tmp/721c7d17-f810-41a8-8c1c-a7e8cd2e52d0",
  "filename": "invoice.pdf"
}

​
Path Parameters

ParameterTypeRequiredDescription
sessionIduuidYesThe session ID

​
Body Parameters

ParameterTypeRequiredDescription
keystringYesThe key returned from the signed URL request
filenamestringYesOriginal filename (for display and format detection)

​
Supported Formats

  • PDF (.pdf)
  • Microsoft Word (.docx, .doc)
  • Images (.png, .jpg, .jpeg, .tiff)
  • PowerPoint (.pptx)

​
Response

201 Created – Document record created and queued for processing. 
{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "filename": "invoice.pdf",
  "status": "uploaded",
  "extraction_session_id": "770e8400-e29b-41d4-a716-446655440000",
  "meta": {},
  "created_at": "2024-01-15T10:30:00Z"
}
Document processing starts automatically. The status will change from uploaded → processing → ready.
422 Unprocessable Entity – Invalid key or unsupported file format.

​
Quick Reference: Complete Upload Flow

1

Get signed upload URL

curl -X POST 'https://api.raydocs.com/vapor/signed-storage-url' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"visibility": "private"}'
Returns url, key, and headers for the S3 upload.
2

Upload file to S3

curl -X PUT "${SIGNED_URL}" \
  -H 'Content-Type: application/pdf' \
  --data-binary @invoice.pdf
3

Create document record (this endpoint)

curl -X POST 'https://api.raydocs.com/extractions/sessions/{sessionId}/documents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"key": "tmp/abc123-...", "filename": "invoice.pdf"}'
For detailed code examples in JavaScript and Python, see the Uploading Documents cookbook.

Authorizations

​
Authorization
string
header
required

Personal Access Token created from the Raydocs dashboard. Include in the Authorization header: Bearer <your_token> See API Keys for token creation and management.

Path Parameters

​
sessionId
string<uuid>
required

Body

multipart/form-data
​
file
file
required

PDF, PNG, JPG, or other supported file

Response

Uploaded

​
id
string<uuid>
​
filename
string
​
mime_type
string
​
size
integer

File size in bytes

​
status
enum<string>
Available options:
pending,
parsing,
parsed,
failed
​
extraction_session_id
string<uuid>
​
created_at
string<date-time>