Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

OAuth2 Authorization Code flow

Body

application/json
filename
string
required

Original filename with extension (max 900 bytes)

Example:

"Annual Report 2024.pdf"

content_type
string
required

MIME content type

Example:

"application/pdf"

purpose
enum<string>
required

Purpose of the upload

Available options:
agent,
knowledge,
skill,
metadata,
dataset,
company,
page,
session,
page_run_output,
export,
whatsapp,
fiscal_document
Example:

"company"

size_bytes
number

File size in bytes (optional, for validation)

Example:

1048576

entity_type
string

Entity type to link this file to (e.g. "company", "person", "lawsuit")

Example:

"company"

entity_id
string

Entity ID to link this file to

Example:

"cmp_abc123"

content_hash
string

SHA-256 hex hash of the file content for deduplication

Example:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

source_url
string

Source URL (for files downloaded from external sources). Used for deduplication - prevents downloading the same file multiple times

Example:

"https://example.com/certificate.pdf"

page_id
string

Page ID to associate this file with (optional)

Example:

"page_abc123"

public
boolean

Whether this file can be fetched without authentication through its public URL

Example:

false

agent_id
string

Agent ID for agent uploads (required when purpose=agent)

Example:

"agt_abc123"

agent_version
string

Agent version name for agent uploads (required when purpose=agent)

Example:

"2026-02-08-10-00-00"

Response

201 - application/json
object
string
required

Object type

Example:

"page"

id
string
required

Unique identifier

Example:

"p_abc123"

createdAt
string<date-time>
required

Creation timestamp

Example:

"2024-01-15T10:30:00.000Z"

updatedAt
string<date-time>
required

Last update timestamp

Example:

"2024-01-15T14:45:00.000Z"

status
enum<string>
required

Upload status

  • pending: Waiting for client upload
  • uploaded: Successfully uploaded
  • failed: Upload failed or expired
Available options:
pending,
uploaded,
failed
Example:

"uploaded"

filename
string
required

Original filename

Example:

"report.pdf"

content_type
string
required

MIME content type

Example:

"application/pdf"

size_bytes
number | null
required

File size in bytes (null if not yet uploaded)

Example:

1048576

metadata
object | null
required

File metadata. PDF page count is stored at metadata.page_count when available.

Example:
uploaded_time
string<date-time> | null
required

When the file was successfully uploaded (null if pending)

Example:

"2024-11-14T10:31:23.456Z"

expires_at
string
required

When the upload URL expires (ISO 8601 string for API response)

Example:

"2024-11-14T11:30:00.000Z"

public
boolean
required

Whether this file can be fetched without authentication through public_url.

Example:

false

classification
object
required

Document classification stage - determines document type and next stages

parse
object
required

Parse stage - converts OCR output to markdown

index
object
required

Index stage - vector embedding for semantic search

insights
object
required

Insights stage - skill-based analysis generating claims/issues/checks

createdBy
Created by · object

Principal who created this object

Example:
updatedBy
Updated by · object

Principal who last updated this object

Example:
reused
boolean

Whether this response reuses an existing file (content-based dedup)

Example:

false

upload_url
string

Presigned S3 upload URL (only present when status is 'pending' and reused is false) Client should PUT file contents to this URL Expires after 1 hour

Example:

"https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."

upload_headers
object

Extra headers required for uploading to the presigned URL (only present when status is pending).

url
string

Authenticated files URL (CloudFront signed cookies) Only present when the file has an S3 key

Example:

"https://files.base39.cloud/uploads/org_abc/fl_abc123/report.pdf"

preview_url
string

Authenticated preview URL for the first generated thumbnail page. Only present when a preview image exists.

Example:

"https://files.base39.cloud/uploads/org_abc/fl_abc123/preview/page-01.png"

download_url
string

Presigned S3 download URL. Only returned when explicitly requested via ?fields=downloadUrl and status is 'uploaded'. Expires after 1 hour.

Example:

"https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."

page_id
string

Page ID associated with this file upload (optional)

Example:

"page_abc123"

purpose
enum<string> | null

Upload purpose

Available options:
agent,
knowledge,
skill,
metadata,
dataset,
company,
page,
session,
page_run_output,
export,
whatsapp,
fiscal_document
public_url
string

Direct files URL. Only present when public is true.

Example:

"https://files.base39.com.br/uploads/org_abc/fl_abc123/report.pdf"

resources
object[] | null

Provider-specific file resources attached to this upload.