Upload Document

Request a presigned S3 upload URL and receive a document_key. All inference APIs — Parse, Extract, Classify, and Split — accept this key instead of a raw file, so a single upload can be reused across multiple operations within 24 hours.

Get a presigned upload URL

Call POST /v1/documents/upload (through Kong) — returns a document_key and a presigned upload_url.

Upload the file bytes to S3

PUT directly to {upload_url}. No API key needed — the URL is pre-authenticated and valid for 15 minutes.

Call any inference API

Pass the document_key to any endpoint. The key is reusable for 24 hours.

Parse Extract Classify Split

Request

Headers

Name	Type	Required	Description
`X-API-Key`	`string`	required	Your API key (hk_live_ or hk_test_).
`Content-Type`	`string`	required	Must be application/json.

Body application/json

Name	Type	Required	Description
`filename`	`string`	required	Original filename including extension (e.g. "invoice.pdf"). Used for MIME auto-detection if content_type is omitted.
`content_type`	`string`	optional	MIME type of the file. Supported: application/pdf, image/jpeg, image/png, image/tiff, image/webp. Defaults to application/pdf.
`content_length`	`integer`	optional	File size in bytes. Enables server-side size validation before the presigned URL is issued (max 50 MB).

Code examples

# Step 1: Request a presigned S3 upload URL
RESP=$(curl -sX POST "https://apis.hyperbots.com/v1/documents/upload" \
  -H "X-API-Key: hk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename":"document.pdf","content_type":"application/pdf"}')

KEY=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['document_key'])")
URL=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_url'])")

# Step 2: PUT the file directly to S3 (no API key needed — URL is pre-authenticated)
curl -X PUT "$URL" \
  -H "Content-Type: application/pdf" \
  -H "x-amz-server-side-encryption: AES256" \
  --data-binary @document.pdf

# document_key is now ready — pass it to /v1/parse, /v1/extract, etc.
echo "$KEY"  # 550e8400-e29b-41d4-a716-446655440000

# Step 1: Request a presigned S3 upload URL
RESP=$(curl -sX POST "https://apis.hyperbots.com/v1/documents/upload" \
  -H "X-API-Key: hk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename":"document.pdf","content_type":"application/pdf"}')

KEY=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['document_key'])")
URL=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_url'])")

# Step 2: PUT the file directly to S3 (no API key needed — URL is pre-authenticated)
curl -X PUT "$URL" \
  -H "Content-Type: application/pdf" \
  -H "x-amz-server-side-encryption: AES256" \
  --data-binary @document.pdf

# document_key is now ready — pass it to /v1/parse, /v1/extract, etc.
echo "$KEY"  # 550e8400-e29b-41d4-a716-446655440000

Response

200 OK

application/json

Field	Type	Description
`document_key` key	`string`	UUID identifying this upload. Pass to any inference endpoint (Parse, Extract, Classify, Split) as a form field.
`upload_url`	`string`	Pre-authenticated S3 PUT URL. Upload the file bytes directly here — no API key required. Valid for expires_in seconds.
`expires_in`	`integer`	Presigned URL TTL in seconds (default 900 = 15 minutes). The file itself is retained in storage for 24 hours.

JSON

{
  "document_key": "550e8400-e29b-41d4-a716-446655440000",
  "upload_url": "https://hyperapi-documents.s3.amazonaws.com/uploads/org_abc/550e8400-...?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...",
  "expires_in": 900
}

{
  "document_key": "550e8400-e29b-41d4-a716-446655440000",
  "upload_url": "https://hyperapi-documents.s3.amazonaws.com/uploads/org_abc/550e8400-...?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...",
  "expires_in": 900
}