Reserve a document upload slot | Pyramid AI

curl -X POST https://api.pyramid-ai.com/api/v2/documents \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "file_name": "Safety-Management-Plan-2026.pdf",
  "content_type": "application/pdf",
  "size_bytes": 2048576,
  "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f"
}'

{
  "request_id": "req_9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "success": true,
  "data": {
    "chunk_count": 4,
    "content_type": "application/pdf",
    "created_at": "2024-04-20T14:22:00Z",
    "error_message": "",
    "file_name": "Safety-Management-Plan-2026.pdf",
    "id": "d4f1a2b3-c5e6-7f89-0a1b-2c3d4e5f6789",
    "org_id": "org_ais",
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "size_bytes": 2048576,
    "status": "awaiting_upload",
    "updated_at": "2024-04-20T14:22:00Z",
    "upload": {
      "url": "https://storage.pyramid-ai.com/uploads/d4f1a2b3-c5e6-7f89-0a1b-2c3d4e5f6789",
      "method": "PUT",
      "recommended_content_type": "application/pdf",
      "expires_at": "2024-04-20T15:22:00Z"
    }
  },
  "pagination": {
    "total": 127,
    "offset": 0,
    "limit": 50
  }
}

Step 1 of the two-step upload flow. Returns a presigned URL for direct PUT to storage. After uploading, call POST /documents/process to kick off processing.

Authentication

AuthorizationBearer

Pyramid API key (prefix with “Bearer ”)

Request

This endpoint expects an object.

file_namestringRequiredformat: "^[^/\\\\]+$"1-500 characters

File name only. Path separators are forbidden.

content_typestringRequired

MIME type. Must be in the allowed set (application/pdf, application/msword, text/plain, etc.).

size_bytesintegerRequired1-524288000

File size in bytes. Used for upload verification.

project_idstringOptionalformat: "uuid"

Which project this document belongs to. Optional — omit for organization-level documents.

Response

Document reserved with upload URL

request_idstringformat: "uuid"

Server-generated per-request UUID. Also sent as X-Request-Id response header. Include in support tickets.

successany

dataobject

paginationobject

Present only on list endpoints. Top-level (not nested inside data).

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error