Skip to content
Sergo

HTTP API

Upload a document

POST
/v1/documents
curl --request POST \
  --url https://sergo.example.com/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=example \
  --form folder_id=example \
  --form preset_id=example \
  --form model_id=example \
  --form max_credits=1

Upload one file as form data. Needs a personal key that can write (sgk_uw_…); other keys get 422 read_only_key.

Without preset_id the file waits as Not processed until someone picks a preset in the console. With preset_id it is processed as it arrives. If a language model reads it, also send model_id and max_credits: the file waits for its page count and is processed only if the estimate fits — deferred_approval says what happened.

If the name is taken in the folder, it gets a number, such as Budget (1).pdf.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typemultipart/form-data
UploadDocumentForm
object
file
required
File

The file

string
folder_id
Folder Id

The folder to put it in, which the key’s owner must manage. Without it, the file goes to their My documents

Any of:
string
preset_id
Preset Id

Process it with this preset as it arrives — see List presets

Any of:
string
model_id
Model Id

When the preset reads this file with a language model: which model — see List models

Any of:
string
max_credits
Max Credits

With model_id: the most this file may cost, in credits

Any of:
number

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
Document
object
id
required
Id
string
name
required
Name

The file name, with its extension

string
folder_id
required
Folder Id

The folder it is in

string
format
required
Format

The file type processing sees, such as pdf or docx

Any of:
string
size_bytes
required
Size Bytes

The size of the original

Any of:
integer
page_count
required
Page Count

Pages of the PDF, or of the PDF copy of an Office file

Any of:
integer
pages_estimated
required
Pages Estimated

The page numbers are estimates, for a file without pages of its own

boolean
chunk_count
required
Chunk Count

How many chunks of text processing made

integer
indexed
required
Indexed

All its chunks are in the search index

boolean
pages_to_view
required
Pages To View

Pages whose text may miss a figure, chart or table — worth looking at as a picture

Array<integer>
default:
processing
required
Processing
object
state
required
State

none (never processed: Not processed), queued, running, done or failed

string
Allowed values: none queued running done failed
waiting_for
required
Waiting For

When queued, what it waits for: its PDF copy, its turn, or the time to try again

Any of:
string
Allowed values: conversion turn retry
stalled
required
Stalled

No processor for this is running — it carries on when one starts

boolean
retry_at
required
Retry At

When it tries again, after a failure that may pass

Any of:
string
preset
required

The preset of the latest processing

Any of:
Ref
object
id
required
Id
string
name
required
Name

Its name, or null if it was deleted

Any of:
string
processor
required

The processor that read the file

Any of:
Ref
object
id
required
Id
string
name
required
Name

Its name, or null if it was deleted

Any of:
string
error
required
Error

Why it failed, or why it is trying again

Any of:
string
warnings
required
Warnings

Things to know, such as pages with no text

Array<string>
changed_at
required
Changed At

When the state last changed

Any of:
string
rendition_format
required
Rendition Format

pdf when it read the PDF copy of an Office file, null when it read the original

Any of:
string
done_page_count
required
Done Page Count

While a model reads page by page, how many pages it has read

Any of:
integer
deferred_approval
required

For a file uploaded with preset_id that a model reads: whether it started

Any of:
DeferredApproval
object
state
required
State

measuring: waiting for a page count before it starts. rejected: it was not processed

string
Allowed values: measuring rejected
reason
required
Reason

Why it was not processed, such as an estimate over max_credits

Any of:
string
estimate
required
Estimate

The estimated cost, once the pages are counted

Any of:
number
shared_with
required
Shared With

People this file was shared with on its own

Array<object>
default:
PersonRef
object
username
required
Username

The person’s username — it may be an email address

string
name
required
Name

The person’s display name

string
uploaded_by
required
PersonRef
object
username
required
Username

The person’s username — it may be an email address

string
name
required
Name

The person’s display name

string
uploaded_at
required
Uploaded At
string

Example 

{
  "chunk_count": 14,
  "folder_id": "Hn3pX7cR",
  "format": "pdf",
  "id": "4kTq8Wmz",
  "indexed": true,
  "name": "Leave policy.pdf",
  "page_count": 12,
  "pages_estimated": false,
  "pages_to_view": [
    5
  ],
  "processing": {
    "changed_at": "2026-11-02T09:14:03+00:00",
    "preset": {
      "id": "basic",
      "name": "Basic"
    },
    "processor": {
      "id": "read-pdf.pypdfium2",
      "name": "PDF text layer"
    },
    "stalled": false,
    "state": "done",
    "warnings": []
  },
  "shared_with": [],
  "size_bytes": 482113,
  "uploaded_at": "2026-11-02T09:13:51+00:00",
  "uploaded_by": {
    "name": "Ava Bennett",
    "username": "ava-hr"
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
RequestError
object
code
required
Code
string
Allowed value: invalid_request
message
required
Message

What was wrong, field by field

string

Example 

{
  "code": "invalid_request"
}