Skip to main content
POST
/
extractions
/
sessions
/
{sessionId}
/
documents
/
upload
Upload Session Documents
curl --request POST \
  --url https://api.raydocs.com/extractions/sessions/{sessionId}/documents/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keys": [
    "<string>"
  ]
}
'
{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "workspace_id": 123,
      "filename": "<string>",
      "mime": "<string>",
      "size": 123,
      "sha256": "<string>",
      "source_url": "<string>",
      "parsings": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "config_hash": "<string>",
          "parser_version": "<string>",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "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 handles upload attach: create or reuse workspace documents from uploaded key(s). To attach already existing documents, use POST /extractions/sessions/{sessionId}/documents/attach.

​
Authentication & Scope

Requires the sessions-write ability.

​
Request

This endpoint expects JSON (not binary upload). 
POST /extractions/sessions/770e8400-e29b-41d4-a716-446655440000/documents/upload HTTP/1.1
Host: api.raydocs.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "keys": ["tmp/721c7d17-f810-41a8-8c1c-a7e8cd2e52d0"]
}

​
Path Parameters

ParameterTypeRequiredDescription
sessionIduuidYesThe session ID

​
Body Parameters

ParameterTypeRequiredDescription
keysarray[string]YesUpload key list from signed URL flow

​
Supported Formats

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

​
Response

200 OK – Documents attached. 
{
  "data": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
      "filename": "invoice.pdf",
      "sha256": "6de7f6f5894c9f3fd1f6f8a4d1b3115d0d9b4b19d7a8a661f9fe90f9c2d80c3b",
      "status": "uploaded",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Upload/import is storage-only. Parsing is requested explicitly (reparse endpoint) or at extraction run time when required.
Deduplication is content-based at workspace scope. If uploaded bytes match an existing document (sha256), the API reuses that document and only creates the session attachment.
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/upload' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"keys": ["tmp/abc123-..."]}'
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

application/json
​
keys
string[]
required

Temporary upload keys returned by /vapor/signed-storage-url

Response

Documents attached

​
data
object[]