Skip to content
Sergo

HTTP API

List documents

GET
/v1/documents
curl --request GET \
  --url https://sergo.example.com/v1/documents \
  --header 'Authorization: Bearer <token>'

The documents the key can read, newest first.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
folder_id
Folder Id

Only the documents directly in this folder

Any of:
string

Only the documents directly in this folder

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
DocumentList
object
items
required
Items
Array<object>
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 

{
  "items": [
    {
      "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"
}