# docAnalyzer.ai API

Version: 2025-01-16

The docAnalyzer.ai REST API. See the quick start and guide.

Base URL: `https://api.docanalyzer.ai/api/v1`
Authentication: bearer token via the Authorization header

## Settings

### GET /models

List all models

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: An array of models Object
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "id": "string",
      "label": "string"
    }
  ]
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/models' \
  --header 'Authorization: Bearer <api_key>'
```

### GET /models/{options}

List models filtered by options

**Path parameters**
- `options` (string, required): Comma-separated options (e.g., byok) that get an optional models list. If byok, the server returns the byok models.

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: An array of models Object
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "id": "string",
      "label": "string"
    }
  ]
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/models/string' \
  --header 'Authorization: Bearer <api_key>'
```

## Credits

### GET /credits

List credits usage for the API key

**Query parameters**
- `start` (string (date-time)): ISO start timestamp (inclusive). Defaults to the first day of the current month when omitted.
- `end` (string (date-time)): ISO end timestamp (exclusive). Defaults to the end of the month for the start date when omitted; max 31 days.
- `reason` (string): Filter by reason group. If omitted or invalid, returns all reasons.
- `workspace` (integer (int32)): Filter by workspace id.
- `limit` (integer (int32)): Maximum number of ledger entries to return.
- `cursor` (string (date-time)): Cursor for pagination. Use nextCursor from the previous response.

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Credits usage summary and ledger.
- `401`: Unauthorized
- `default`: Error response.

Example response (`200`):
```json
{
  "data": {
    "summary": {
      "start": "2025-01-16T09:00:00Z",
      "end": "2025-01-16T09:00:00Z",
      "count": 0,
      "monthly_delta": 0,
      "bundle_delta": 0
    },
    "ledger": {
      "items": [
        {
          "event_ts": "2025-01-16T09:00:00Z",
          "reason": "string",
          "workspace": 0,
          "delta_monthly": 0,
          "delta_bundle": 0,
          "request_id": "string"
        }
      ],
      "nextCursor": "2025-01-16T09:00:00Z"
    }
  }
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/credits' \
  --header 'Authorization: Bearer <api_key>'
```

## Documents

### GET /doc

List all documents in a given workspace

**Query parameters**
- `offset` (integer (int32))
- `limit` (integer (int32))

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: A paged array of documents
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "docid": "string",
      "workspace": 0,
      "name": "string",
      "metadata": {},
      "ready": true
    }
  ]
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/doc' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>'
```

### POST /doc

Create a document from a URL

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `url` (string (uri), required): Publicly accessible URL to fetch the file from
- `name` (string): Display name to use for the created document. If omitted, the URL will be used.

Example:
```json
{
  "url": "https://example.com/file.pdf",
  "name": "string"
}
```

**Responses**
- `200`: Document created successfully
- `400`: Invalid request or failed to fetch URL
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    "string"
  ]
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/doc' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://example.com/file.pdf","name":"string"}'
```

### POST /doc/upload/{options}

Upload document(s)

**Path parameters**
- `options` (array of string, required): Comma-separated options (e.g.,sync) that modify upload behavior. If sync, the server wait document(s) analysis is ready to return.

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (multipart/form-data)
- `file` (array of string)
  - `items` (string)

Example:
```json
{
  "file": [
    "string"
  ]
}
```

**Responses**
- `200`: Null response
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "docid": "string",
      "workspace": 0,
      "name": "string",
      "metadata": {},
      "ready": true
    }
  ]
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/doc/upload/%5B%22string%22%5D' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>'
```

### GET /doc/{docid}

Get document information

**Path parameters**
- `docid` (string, required): The unique identifier of the document to retrieve

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "docid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "ready": true
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/doc/string' \
  --header 'Authorization: Bearer <api_key>'
```

### PUT /doc/{docid}

Update document

**Path parameters**
- `docid` (string, required): The unique identifier of the document to update

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `name` (string): The new display name for the document
- `metadata` (Metadata): You can use this field to attach key-value data to a label/document. Up to 20 keys; keys up to 40 characters; values up…
  - `*` (string)

Example:
```json
{
  "name": "string",
  "metadata": {}
}
```

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "docid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "ready": true
}
```

Example request:
```sh
curl --location --request PUT 'https://api.docanalyzer.ai/api/v1/doc/string' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"string","metadata":{}}'
```

### DELETE /doc/{docid}

Delete document

**Path parameters**
- `docid` (string, required): The unique identifier of the document to delete

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "docid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "ready": true
}
```

Example request:
```sh
curl --location --request DELETE 'https://api.docanalyzer.ai/api/v1/doc/string' \
  --header 'Authorization: Bearer <api_key>'
```

### GET /doc/{docid}/link

Get a document link

**Path parameters**
- `docid` (string, required): The unique identifier of the document to retrieve

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "data": {
    "link": "string"
  }
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/doc/string/link' \
  --header 'Authorization: Bearer <api_key>'
```

### POST /doc/{docid}/chat

Chat with a document

Each call starts a new conversation thread by default; concurrent calls do not interfere with each other. To continue an earlier conversation, capture the tid returned in the response and pass it back as tid in the next request. Only one chat may be in flight per tid at a time — a concurrent call on the same tid returns HTTP 423.

**Path parameters**
- `docid` (string, required): The unique identifier of the document to chat with.

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `prompt` (string, required): The question for the AI.
- `tid` (string): Optional. Continue a previous conversation by passing the tid returned by an earlier call to this endpoint. Must belong…
- `dryrun` (boolean): If true, estimates the maximum credits the request might consume without processing it.
- `model` (string): Specifies the AI model for generating the response. Default: 'gpt-4.1-mini'. Retrieve available model IDs via GET…
- `budget` (number): Maximum number of context tokens (from the prompt and document) to use for the prompt. Defaults and maximums vary by…
- `pcap` (number): Maximum fraction of the context budget that the prompt (input) tokens are allowed to consume. From 5% to 60%.
- `thinking` (string): Specifies the reasoning process for compatible models. Refer to GET /models for valid values specific to each model.
- `page` (boolean): Indicates whether page number references from the source document should be included in the answer.
- `ocap` (number): Sets the maximum number of tokens for the generated answer (output capacity). Defaults and maximums vary by model (see…
- `adherence` (string): Controls how strictly the AI's response must adhere to the provided document's content.
- `lang` (string): Specifies the desired language for the AI's answer.
- `byok` (boolean): Set to true to use a Bring Your Own Key (BYOK) model configured in your account.

Example:
```json
{
  "prompt": "string",
  "tid": "string",
  "dryrun": false,
  "model": "gpt-4.1-mini",
  "budget": 0,
  "pcap": 0.1,
  "thinking": "string",
  "page": true,
  "ocap": 1024,
  "adherence": "balanced",
  "lang": "English",
  "byok": false
}
```

**Responses**
- `200`: Successful response containing the AI's answer.
- `401`: Unauthorized
- `423`: A chat is already in progress on this thread (tid). Wait for the previous response, or omit tid to start a new thread.
- `default`: An unexpected error occurred.

Example response (`200`):
```json
{
  "promptid": "string",
  "tid": "string",
  "answer": "string"
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/doc/string/chat' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"string","tid":"string","dryrun":false,"model":"gpt-4.1-mini","budget":0,"pcap":0.1,"thinking":"string","page":true,"ocap":1024,"adherence":"balanced","lang":"English","byok":false}'
```

### POST /doc/{docid}/ocr

Perform OCR (Optical Character Recognition).

**Path parameters**
- `docid` (string, required): The unique identifier of the document to perform ocr on

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `401`: Unauthorized
- `default`: Error response.

Example response (`200`):
```json
{
  "queue": [
    "string"
  ]
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/doc/string/ocr' \
  --header 'Authorization: Bearer <api_key>'
```

## Labels

### GET /label

List all labels in a given workspace

**Query parameters**
- `offset` (integer (int32))
- `limit` (integer (int32))

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: A paged array of labels
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "lid": "string",
      "labelid": "string",
      "workspace": 0,
      "name": "string",
      "metadata": {},
      "docids": [
        "string"
      ],
      "color": "string"
    }
  ]
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/label' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>'
```

### POST /label

Create a label

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `name` (string, required): Display name for the label
- `metadata` (Metadata): You can use this field to attach key-value data to a label/document. Up to 20 keys; keys up to 40 characters; values up…
  - `*` (string)
- `docids` (array of string): Unique identifiers of documents associated with the label
  - `items` (string)
- `color` (string, required): The hex color code of the label

Example:
```json
{
  "name": "string",
  "metadata": {},
  "docids": [
    "string"
  ],
  "color": "string"
}
```

**Responses**
- `200`: A paged array of labels
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "lid": "string",
      "labelid": "string",
      "workspace": 0,
      "name": "string",
      "metadata": {},
      "docids": [
        "string"
      ],
      "color": "string"
    }
  ]
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/label' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"string","metadata":{},"docids":["string"],"color":"string"}'
```

### POST /label/{labelid}/upload/{options}

Upload documents associated with label(s)

**Path parameters**
- `labelid` (array of string, required): Label identifier(s) to associate documents with (labelid preferred; legacy UUID lid supported).
- `options` (array of string, required): Comma-separated options (e.g.,sync) that modify upload behavior. If sync, the server wait document(s) analysis is ready to return.

**Header parameters**
- `da-workspace` (integer): The workspace to use
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (multipart/form-data)
- `file` (array of string)
  - `items` (string)

Example:
```json
{
  "file": [
    "string"
  ]
}
```

**Responses**
- `200`: Null response
- `default`: Error response.

Example response (`200`):
```json
{
  "data": [
    {
      "lid": "string",
      "labelid": "string",
      "workspace": 0,
      "name": "string",
      "metadata": {},
      "docids": [
        "string"
      ],
      "color": "string"
    }
  ]
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/label/%5B%22string%22%5D/upload/%5B%22string%22%5D' \
  --header 'da-workspace: 0' \
  --header 'Authorization: Bearer <api_key>'
```

### GET /label/{labelid}

Get label information

**Path parameters**
- `labelid` (string, required): The label identifier to retrieve (labelid preferred; legacy UUID lid supported).

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "lid": "string",
  "labelid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "docids": [
    "string"
  ],
  "color": "string"
}
```

Example request:
```sh
curl --location 'https://api.docanalyzer.ai/api/v1/label/string' \
  --header 'Authorization: Bearer <api_key>'
```

### PUT /label/{labelid}

Update label

**Path parameters**
- `labelid` (string, required): The label identifier to update (labelid preferred; legacy UUID lid supported).

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `name` (string): The new display name for the label
- `metadata` (Metadata): You can use this field to attach key-value data to a label/document. Up to 20 keys; keys up to 40 characters; values up…
  - `*` (string)
- `color` (string): The new hex color code for the label
- `docids` (object)
  - `tag` (array of string): Tag the document(s) with this label
    - `items` (string)
  - `untag` (array of string): Untag the document(s) with this label
    - `items` (string)

Example:
```json
{
  "name": "string",
  "metadata": {},
  "color": "string",
  "docids": {
    "tag": [
      "string"
    ],
    "untag": [
      "string"
    ]
  }
}
```

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "lid": "string",
  "labelid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "docids": [
    "string"
  ],
  "color": "string"
}
```

Example request:
```sh
curl --location --request PUT 'https://api.docanalyzer.ai/api/v1/label/string' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"string","metadata":{},"color":"string","docids":{"tag":["string"],"untag":["string"]}}'
```

### DELETE /label/{labelid}

Delete label

**Path parameters**
- `labelid` (string, required): The label identifier to delete (labelid preferred; legacy UUID lid supported).

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Responses**
- `200`: Expected response to a valid request
- `default`: Error response.

Example response (`200`):
```json
{
  "lid": "string",
  "labelid": "string",
  "workspace": 0,
  "name": "string",
  "metadata": {},
  "docids": [
    "string"
  ],
  "color": "string"
}
```

Example request:
```sh
curl --location --request DELETE 'https://api.docanalyzer.ai/api/v1/label/string' \
  --header 'Authorization: Bearer <api_key>'
```

### POST /label/{labelid}/chat

Chat with all documents associated with a label

Each call starts a new conversation thread by default; concurrent calls (e.g. one per logged event) run independently. To continue an earlier conversation, capture the tid returned in the response and pass it back as tid in the next request. Only one chat may be in flight per tid at a time — a concurrent call on the same tid returns HTTP 423.

**Path parameters**
- `labelid` (string, required): The label identifier to chat with (labelid preferred; legacy UUID lid supported).

**Header parameters**
- `Authorization` (string, required): Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>

**Request body** (application/json, required)
- `prompt` (string, required): The question for the AI.
- `tid` (string): Optional. Continue a previous conversation by passing the tid returned by an earlier call to this endpoint. Must belong…
- `dryrun` (boolean): If true, estimates the maximum credits the request might consume without processing it.
- `model` (string): Specifies the AI model for generating the response. Default: 'gpt-4.1-mini'. Retrieve available model IDs via GET…
- `budget` (number): Maximum number of context tokens (from the prompt and documents) to use for the prompt. Defaults and maximums vary by…
- `pcap` (number): Maximum fraction of the context budget that the prompt (input) tokens are allowed to consume. From 5% to 60%.
- `thinking` (string): Specifies the reasoning process for compatible models. Refer to GET /models for valid values specific to each model.
- `page` (boolean): Indicates whether page number references from the source documents should be included in the answer.
- `ocap` (number): Sets the maximum number of tokens for the generated answer (output capacity). Defaults and maximums vary by model (see…
- `adherence` (string): Controls how strictly the AI's response must adhere to the provided documents' content.
- `lang` (string): Specifies the desired language for the AI's answer.
- `byok` (boolean): Set to true to use a Bring Your Own Key (BYOK) model configured in your account.

Example:
```json
{
  "prompt": "string",
  "tid": "string",
  "dryrun": false,
  "model": "gpt-4.1-mini",
  "budget": 0,
  "pcap": 0.1,
  "thinking": "string",
  "page": true,
  "ocap": 1024,
  "adherence": "balanced",
  "lang": "English",
  "byok": false
}
```

**Responses**
- `200`: Successful response containing the AI's answer.
- `401`: Unauthorized
- `423`: A chat is already in progress on this thread (tid). Wait for the previous response, or omit tid to start a new thread.
- `default`: Error response.

Example response (`200`):
```json
{
  "promptid": "string",
  "tid": "string",
  "answer": "string"
}
```

Example request:
```sh
curl --location --request POST 'https://api.docanalyzer.ai/api/v1/label/string/chat' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"string","tid":"string","dryrun":false,"model":"gpt-4.1-mini","budget":0,"pcap":0.1,"thinking":"string","page":true,"ocap":1024,"adherence":"balanced","lang":"English","byok":false}'
```