docAnalyzer

API Documentation

Getting started with the docAnalyzer API

The docAnalyzer API allows developers to upload, manage, and interact with documents programmatically. This documentation provides everything you need to get started, including endpoints, authentication details, and usage examples.

API Access Requirements

Before you can start using the docAnalyzer API, please ensure the following prerequisites are met:

  1. Paid Subscription: API access is an exclusive feature available only to users on our paid subscription plans. Free plan users will need to upgrade their account to utilize the API functionalities.
  2. Expert Mode: You must enable "Expert Mode" within your account settings. Activating this mode grants access to advanced features, including the API. Navigate to Account Settings -> Features scope to enable this option.

Once you have fulfilled these requirements, you can generate your API key from the API Dashboard and begin integrating with the docAnalyzer API.

Base Endpoint

https://api.docanalyzer.ai

All API requests should be made to this base URL.

Authentication

The docAnalyzer API uses API keys for authentication. You can generate and manage your API keys in the API Dashboard.

Security Note: API keys grant full access to your account’s privileges. Keep them confidential and avoid sharing them in public spaces like GitHub, client-side code, or forums.

Include your API key in the Authorization header of every request:

Authorization: Bearer DOCANALYZER_API_KEY

Replace DOCANALYZER_API_KEY with your actual key.

Quick Start

Get up and running with these common tasks.

List Available Models (GET /api/v1/models/:options?)

Retrieve a list of available AI models and their configurations.

Options

  • byok: Include byok in the URL (e.g., /api/v1/models/byok) to list models supporting bring-your-own-key.

Example

curl https://api.docanalyzer.ai/api/v1/models \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": [
    {
      "id": "model1",
      "label": "Model One",
      "defaultContextBudget": 1000,
      "maxContextBudget": 4000,
      "maxOcap": 2000,
      "defaultThinkingEffort": "medium",
      "thinkingEffortLevels": ["low", "medium", "high"]
    }
  ],
  "error": null
}

Upload a Document (POST /api/v1/doc/upload)

Upload a document using multipart/form-data. Supported file types include PDF, Markdown (MD), JSON, CSV, Text, HTML, OpenDocument Text (ODT), OpenDocument Presentation (ODP), Electronic publication (EPUB), Rich Text Format (RTF), Microsoft OpenXML (DOCX), Microsoft PowerPoint OpenXML (PPTX), and more (see the upload section for a full list).

Fair Use Note: Document uploads via the API are subject to the same fair use and anti-DDoS throttling policies as uploads through the user interface. See our FAQ on Fair Use and Anti-DDoS Policies for details on how throttling may affect upload frequency during peak usage.

Options

  • sync: Include sync in the URL (e.g., /api/v1/doc/upload/sync) to wait for document processing to complete before receiving a response.

Example: Uploading a PDF

curl https://api.docanalyzer.ai/api/v1/doc/upload \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -F "[email protected]"

Example: Uploading a Non-PDF File (e.g., RTF)

Specify the MIME type explicitly for non-PDF files:

curl https://api.docanalyzer.ai/api/v1/doc/upload \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -F "[email protected];type=application/rtf"

Response: A JSON object with the uploaded document’s docid as the first element of the data property (e.g., {"error":null,"data":["dt7xxnv398v26yv3"]}).

List Documents (GET /api/v1/doc)

Retrieve a JSON list of all your uploaded documents, including their docids, readiness status, and names.

Legacy Docids

Older document IDs that did not start with d have been migrated to the new format d<old_id>. The /api/v1/doc/{docid} family of endpoints still accepts the legacy ID and redirects to the new one.

Optional Query Parameters

  • offset: Starting point for pagination (default: 0).
  • limit: Number of documents to return (default: 100).

Example

curl https://api.docanalyzer.ai/api/v1/doc \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": [
    {
      "docid": "da6pvxq9avzwhnb3",
      "ready": true,
      "name": "test1.pdf",
      "metadata": { "ClientId": "ACME123" }
    },
    { "docid": "dt7xxnv398z26yv3", "ready": true, "name": "testdoc2.rtf" }
  ],
  "error": null
}

Pagination: If more documents are available, the response includes an X-Next header with the URL for the next page (e.g., /api/v1/doc?offset=10&limit=10).

Chat with a Document (POST /api/v1/doc/{docid}/chat)

Ask a question about a specific document and receive a response. By default each call starts a new conversation thread, and concurrent calls do not interfere with each other. To continue a previous conversation, capture the tid returned in the response and pass it back as tid in the next request.

Request Body Parameters

  • prompt (required): The question or instruction for the document.
  • tid (string, optional): Continue a previous conversation by passing the tid returned by an earlier call to this endpoint. The tid must belong to the same document. Only one chat can be in flight per tid at a time (a concurrent call on the same tid returns HTTP 423 Locked). Omit tid to start a fresh thread, recommended for stateless / event-driven integrations.
  • dryrun (boolean, default: false): If true, returns estimated credit cost without executing the query.
  • byok (boolean): If true, uses a bring-your-own-key model (requires a valid secret set in your account).
  • model (string): The AI model to use (e.g., default model if not specified). See /models endpoint for available models.
  • budget (number): Context token limit (defaults to model’s base budget).
  • pcap (number, default: 0.1): Maximum fraction of the context budget that the prompt (input) tokens can consume. Must be between 0.05 (5%) and 0.6 (60%).
  • thinking (string): Thinking effort level for models that support it (e.g., low, medium, high).
  • page (boolean, default: true): If false, disables specific location references (e.g., PAGE!5).
  • ocap (number): Output token limit.
  • adherence (string, default: balanced): How strictly the response adheres to document content (strict, high, balanced, low, free).
  • lang (string): Language for the response (if supported by the model).

Example

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"prompt": "What is the main topic of this document?", "adherence": "strict"}' \
    https://api.docanalyzer.ai/api/v1/doc/dt7xnnv398z26yv3/chat

Response Example:

{
  "data": {
    "promptid": "iim3vxgwezhjp0h",
    "tid": "tabc123def456ghi",
    "answer": "The main topic is project planning. See PAGE!3 for details.",
    "docids": ["dt7xnnv398z26yv3"]
  },
  "error": null,
  "credits": 5
}

Get Document Details (GET /api/v1/doc/{docid})

Retrieve details for a specific document, including associated labels.

Example

curl https://api.docanalyzer.ai/api/v1/doc/dt7xnnv398z26yv3 \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": {
    "docid": "dt7xnnv398z26yv3",
    "ready": true,
    "name": "testdoc2.rtf",
    "metadata": { "ClientId": "ACME123", "Project": "Delta" },
    "labels": [{ "name": "Project Docs", "color": "#ff0000" }]
  },
  "error": null
}

Update Document (PUT /api/v1/doc/{docid})

Update a document's name or metadata.

Request Body Parameters

  • name (optional): New document name.
  • metadata (optional): User-managed key-value data (see Metadata section below for constraints).

Example

curl -X PUT https://api.docanalyzer.ai/api/v1/doc/dt7xnnv398z26yv3 \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"name": "Updated Doc", "metadata": {"ClientId": "ACME123"}}'

Response Example:

{
  "data": {
    "docid": "dt7xnnv398z26yv3",
    "ready": true,
    "name": "Updated Doc",
    "metadata": { "ClientId": "ACME123" }
  },
  "error": null
}

Metadata (Documents and Labels)

You can use the metadata field to attach key-value data to a document or label. This field is only managed by you; docAnalyzer does not interpret or modify it.

Constraints:

  • Up to 20 keys.
  • Key names up to 40 characters long.
  • Values up to 200 characters long.
  • Keys and values must be strings.
  • Keys may contain only letters and numbers (no spaces or punctuation).

Delete Document (DELETE /api/v1/doc/{docid})

Delete a specific document.

Example

curl -X DELETE https://api.docanalyzer.ai/api/v1/doc/dt7xnnv398z26yv3 \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": [
    {
      "docid": "dt7xnnv398z26yv3",
      "ready": true,
      "name": "testdoc2.rtf",
      "metadata": { "ClientId": "ACME123" }
    }
  ],
  "error": null
}

OCR Document (POST /api/v1/doc/{docid}/ocr)

Perform OCR on a specific document (use 1 credit per page).

Example

curl -X POST https://api.docanalyzer.ai/api/v1/doc/dt7xnnv398z26yv3/ocr \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": {
    "queue": ["<ocr workflow id>"]
  },
  "error": null
}

Document References in Responses

When chatting with documents via the /api/v1/doc/{docid}/chat or /api/v1/label/{labelid}/chat endpoints, the answer field in the response may include special reference markers to indicate where information is sourced from within the documents. These markers help developers trace answers back to specific parts of the document(s).

How References Appear

  • Multiple Documents: When multiple documents are involved (e.g., chatting with a label containing multiple docids), references use the format SOURCE_<number> or SOURCE_<number>_<TYPE>!<value>. The <number> corresponds to the order of docids in the request.
    • Example: See SOURCE_2_PAGE!34 refers to page 34 of the second document in the list.
  • Single Document: For a single document (e.g., /api/v1/doc/{docid}/chat), references use a simpler format like <TYPE>!<value>.
    • Example: See PAGE!5 refers to page 5 of the document.

Reference Types

  • PAGE!<page_number>: Indicates a specific page in a paginated document (e.g., PDF).
    • Example: PAGE!12 or SOURCE_1_PAGE!12.
  • SECTION!<section_number>: Indicates a section in a flowable document (e.g., Markdown).
    • Example: SECTION!3 or SOURCE_2_SECTION!3.
  • PATH!: Indicates a path in a schematic document (e.g., JSON).
    • Example: PATH!users.profile or SOURCE_3_PATH!users.profile.

Controlling References

  • Page Parameter: Set page: false in the request body to disable specific location references (e.g., PAGE!<page_number>).
    • Example: {"prompt": "Summarize this", "page": false}.
  • Adherence Parameter: The adherence level (strict, high, balanced, low, free) affects how strictly the response adheres to the document context, which may influence the frequency of references.

Example with References

Request

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"prompt": "What is discussed on page 5?"}' \
    https://api.docanalyzer.ai/api/v1/doc/dt7xnnv39az26yv3/chat

Response

{
  "data": {
    "promptid": "iim3vxgwezhjp0h",
    "answer": "Page 5 discusses the project timeline. See PAGE!5 for details.",
    "docids": ["dt7xnnv39az26yv3"]
  },
  "error": null,
  "credits": 5
}

Multi-Document Request

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"prompt": "Compare the introductions"}' \
    https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3/chat

Multi-Document Response

{
  "data": {
    "promptid": "xyz789",
    "answer": "SOURCE_1 introduces the topic on PAGE!1, while SOURCE_2 starts with a summary on SECTION!1.",
    "docids": ["dt7xnnv39az26yv3", "dt9xnnv24rtf89v5"]
  },
  "error": null,
  "credits": 10
}

Notes

  • References are only included when the response directly relates to document content and the information can be pinpointed.
  • If no specific location is identifiable, the response may omit references or use a generic SOURCE_<number> marker.

Label Management

Label endpoints now accept labelid (preferred, starts with l) or the legacy UUID lid.

List Labels (GET /api/v1/label)

Retrieve a JSON list of all labels in the workspace.

Example

curl https://api.docanalyzer.ai/api/v1/label \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": [
    {
      "lid": "2f2a1e35-9b1c-4db3-a9b4-3e4c3a40f7a0",
      "labelid": "l9xnnv398z26yv3",
      "name": "Project Docs",
      "color": "#ff0000",
      "docids": ["dt7xnnv398z26yv3"],
      "metadata": { "ClientId": "ACME123" }
    }
  ],
  "error": null
}

Get Label Details (GET /api/v1/label/{labelid})

Retrieve details for a specific label. Provide the labelid (preferred) or the legacy UUID lid.

Example

curl https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3 \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": {
    "lid": "2f2a1e35-9b1c-4db3-a9b4-3e4c3a40f7a0",
    "labelid": "l9xnnv398z26yv3",
    "name": "Project Docs",
    "color": "#ff0000",
    "docids": ["dt7xnnv398z26yv3"],
    "metadata": { "ClientId": "ACME123", "Project": "Delta" }
  },
  "error": null
}

Create Label (POST /api/v1/label)

Create a new label with an optional list of document IDs.

Request Body Parameters

  • name (required): Label name.
  • color (required): Hex color code (e.g., #ff0000).
  • docids (array): List of document IDs to associate with the label.
  • metadata (optional): User-managed key-value data (see Metadata section above for constraints).

Example

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"name": "Project Docs", "color": "#ff0000", "docids": ["dt7xnnv398z26yv3"]}' \
    https://api.docanalyzer.ai/api/v1/label

Response Example:

{
  "data": { "lid": "2f2a1e35-9b1c-4db3-a9b4-3e4c3a40f7a0" },
  "error": null
}

Upload to Label (POST /api/v1/label/{labelid}/upload)

Upload documents and associate them with a specific label.

Options

  • sync: Include sync in the URL (e.g., /api/v1/label/l9xnnv398z26yv3/upload/sync) to wait for document processing to complete.

Example

curl https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3/upload \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -F "[email protected]"

Response Example:

{
  "data": ["dt7xnnv398z26yv3"],
  "error": null
}

Update Label (PUT /api/v1/label/{labelid})

Update a label’s name, color, or associated documents.

Request Body Parameters

  • name (optional): New label name.
  • color (optional): New hex color code.
  • docids (object, optional): Object with tag (array of docids to add) and untag (array of docids to remove).
  • metadata (optional): User-managed key-value data (see Metadata section above for constraints).

Example

curl -X PUT -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"name": "Updated Docs", "docids": {"tag": ["dt9xnnv24rtf89v5"], "untag": ["dt7xnnv398z26yv3"]}}' \
    https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3

Response Example:

{
  "data": {
    "name": "Updated Docs",
    "color": "#ff0000",
    "docids": ["dt9xnnv24rtf89v5"],
    "metadata": { "ClientId": "ACME123" }
  },
  "error": null
}

Delete Label (DELETE /api/v1/label/{labelid})

Delete a specific label.

Example

curl -X DELETE https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3 \
    -H "Authorization: Bearer $DOCANALYZER_API_KEY"

Response Example:

{
  "data": [
    {
      "lid": "2f2a1e35-9b1c-4db3-a9b4-3e4c3a40f7a0",
      "labelid": "l9xnnv398z26yv3",
      "name": "Project Docs",
      "color": "#ff0000",
      "docids": []
    }
  ],
  "error": null
}

Chat with a Label (POST /api/v1/label/{labelid}/chat)

Ask questions about all documents associated with a label. Parameters are the same as for /api/v1/doc/{docid}/chat, including the optional tid parameter for continuing a previous conversation. By default each call starts a new thread, so concurrent calls (e.g. one per logged event) run independently.

Example

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{"prompt": "Compare the introductions"}' \
    https://api.docanalyzer.ai/api/v1/label/l9xnnv398z26yv3/chat

Response Example:

{
  "data": {
    "promptid": "xyz789",
    "tid": "tabc123def456ghi",
    "answer": "SOURCE_1 introduces the topic on PAGE!1, while SOURCE_2 starts with a summary on SECTION!1.",
    "docids": ["dt7xnnv39az26yv3", "dt9xnnv24rtf89v5"]
  },
  "error": null,
  "credits": 10
}

Rate Limits

To ensure fair usage and optimal performance, the API enforces the following limits:

Per-Minute Quota

  • Limit: 100 requests per 60-second rolling window.
  • Behavior: Exceeding this triggers a 429 Too Many Requests error.
  • Monitoring: Check these response headers:
    • X-RateLimit-Limit: Maximum allowed requests (100).
    • X-RateLimit-Remaining: Remaining requests in the current window.

Per-Day Quota

  • Limit: 10,000 requests per UTC day.
  • Behavior: Requests are blocked until the next UTC day starts after reaching the limit.

Credit Usage

When chatting with documents via the /api/v1/doc/{docid}/chat or /api/v1/label/{labelid}/chat endpoints, requests consume credits based on the operation and parameters (e.g., model, budget, thinking effort). Use the dryrun parameter to estimate credit costs without executing the request.

  • Insufficient Credits: Returns a 403 Forbidden error with the message Insufficient Credits.
  • Monthly Credits: Reset monthly, with a default allowance depending on your plan. Excess usage draws from purchased bundle credits.

Credits Ledger (GET /api/v1/credits)

Retrieve a summary and ledger entries for your API key. Team keys return team credits only; personal keys return personal credits only. This scope cannot be overridden.

Query Parameters

  • start (optional): ISO timestamp for range start (inclusive). Defaults to the first day of the current month.
  • end (optional): ISO timestamp for range end (exclusive). Defaults to the end of the month for the start date.
  • reason (optional): chat, chatbot, api, or other.
  • workspace (optional): Workspace id to filter by.
  • limit (optional): Max ledger rows per page (default 100, max 200).
  • cursor (optional): Pagination cursor from nextCursor.

Ranges cannot exceed 31 days.

Example

curl -H "Authorization: Bearer $DOCANALYZER_API_KEY" \
  "https://api.docanalyzer.ai/api/v1/credits?start=2025-01-01T00:00:00Z&end=2025-02-01T00:00:00Z&reason=chat&workspace=0"

Response Example

{
  "data": {
    "summary": {
      "start": "2025-01-01T00:00:00.000Z",
      "end": "2025-02-01T00:00:00.000Z",
      "count": 42,
      "monthly_delta": 120,
      "bundle_delta": -30
    },
    "ledger": {
      "items": [
        {
          "event_ts": "2025-01-15T12:45:00Z",
          "reason": "chat",
          "workspace": 0,
          "delta_monthly": 3,
          "delta_bundle": 0,
          "request_id": "chat:prompt_123"
        }
      ],
      "nextCursor": "2025-01-15T12:45:00Z"
    }
  },
  "error": null
}

Notes:

  • delta_monthly and delta_bundle are user-facing deltas: usage is negative, reset/purchase is positive.

Error Responses

  • 400 Bad Request: Invalid parameters or request body (e.g., unsupported model or adherence).
  • 403 Forbidden: Insufficient credits or unauthorized access.
  • 404 Not Found: Document or label not found.
  • 429 Too Many Requests: Rate limit exceeded.
  • 503 Service Unavailable: docAnalyzer is in maintenance mode.

API Reference

For a complete list of endpoints, parameters, and response formats, visit our Reference Documentation. Note: This is a work in progress and may not yet cover all features.

Community Contributions

Discover and share code samples in our Community Contributions Repository on GitHub. Explore examples in Python, JavaScript, and more. While we don’t provide direct support for these scripts, our Discord community is available to help.

Support

Have questions? Join our Discord community or contact support.

Was this helpful?