Skip to main content
GET
/
v1
/
files
/
{file_id}
Get File
curl --request GET \
  --url https://api.cuadra.ai/v1/files/{file_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "filename": "<string>",
  "contentType": "<string>",
  "sizeBytes": 1,
  "sha256": "<string>",
  "status": "uploading",
  "isDuplicate": true,
  "storageCharged": 1,
  "createdAt": "2023-11-07T05:31:56Z",
  "processingStatus": {
    "progress": 0,
    "error": "Failed to extract text from PDF"
  },
  "processedAt": "2025-01-17T10:02:30Z",
  "associations": [
    {
      "resourceType": "<string>",
      "resourceId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "source": "api",
  "sourceDetail": "dashboard",
  "connectorMetadata": {
    "externalId": "<string>",
    "externalUrl": "https://docs.google.com/document/d/1Bxi...",
    "externalPath": "/Marketing/Q4 Reports/Revenue.pdf",
    "modifiedBy": "Jane Doe",
    "sourceModifiedAt": "2026-01-10T14:30:00Z",
    "labels": [
      "important",
      "q4-review"
    ],
    "extra": {
      "shared": true,
      "starred": false
    }
  }
}

Authorizations

​
Authorization
string
header
required

JWT token from Stytch B2B authentication (magic link, SSO, or M2M)

Path Parameters

​
file_id
string
required

File ID

Example:

"file_abc123"

Query Parameters

​
expand[]
string[] | null

List of related objects to expand in the response. Example: ?expand[]=model&expand[]=versions

Example:
["model"]

Response

File metadata and processing status

File response schema - COMPOSITE SCHEMA. Combines data from multiple sources for API simplicity: - FileEntity: id, filename, created_at (logical file) - FileContent: sha256, size_bytes, content_type, status, processed_at (physical content) - Computed: isDuplicate, storageCharged (deduplication logic) - Relationships: associations (file-resource links) Used for GET /v1/files/{id} and POST /v1/files responses. Deduplication info: - isDuplicate: Whether this file reuses existing content - storageCharged: Actual storage bytes charged (0 for duplicates) - sha256: Content hash for deduplication tracking

​
id
string
required

Unique file identifier

Example:

"file_abc123"

​
filename
string
required

Original filename

Example:

"document.pdf"

​
contentType
string
required

MIME type of the file

Example:

"application/pdf"

​
sizeBytes
integer
required

File size in bytes

Required range: x >= 0
Example:

1048576

​
sha256
string
required

SHA256 hash of file content (for deduplication)

Example:

"abc123def456..."

​
status
enum<string>
required

Processing status

Available options:
uploading,
uploaded,
processing,
ready,
error,
failed
Example:

"ready"

​
isDuplicate
boolean
required

Whether this file reuses existing content (no storage charge)

Example:

false

​
storageCharged
integer
required

Actual storage bytes charged (0 for duplicates)

Required range: x >= 0
Example:

1048576

​
createdAt
string<date-time>
required

File upload timestamp

Example:

"2025-01-17T10:00:00Z"

​
processingStatus
ProcessingStatus · object

Detailed processing status

​
processedAt
string<date-time> | null

When file processing completed

Example:

"2025-01-17T10:02:30Z"

​
associations
FileAssociationOut · object[] | null

Resources this file is associated with (included when expanded with ?expand[]=associations)

​
source
string
default:api

Request origin: api, m2m, connector

Examples:

"api"

"m2m"

"connector"

​
sourceDetail
string | null

Specific source: dashboard, google_drive, notion, etc.

Example:

"dashboard"

​
connectorMetadata
ConnectorMetadata · object

Metadata from external connector (Google Drive, Notion, etc.). Only present for connector-synced files.