API Reference

Build powerful document intelligence workflows. Our REST API gives you full access to AI-powered extraction, analysis, and summary capabilities for your PDF documents.

Authentication

Authentication to the Document Analyzer API is handled via Bearer tokens. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Security Tip: Never share your API keys or commit them to version control. If a key is compromised, revoke it immediately in the developer portal.

GET/v1/me

Get Account Balance

Returns the credit balance and subscription plan details for the API key owner. Use this to check remaining credits before queuing analysis jobs.

Parameters

Name	Type	Description

No scope required — all valid API keys can call this endpoint. `creditsRemaining` will be `0` once the monthly allowance is exhausted; upgrade your plan or wait for the next billing cycle.

cURL Example

curl -X GET "https://docology.hildebrandligtas.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "data": {
    "planId": "free",
    "planName": "Free Plan",
    "creditsTotal": 5,
    "creditsUsed": 2,
    "creditsRemaining": 3,
    "cycleStartedAt": "2026-05-01T00:00:00.000Z"
  }
}

POST/v1/document/upload

Upload a Document

Uploads a file to the platform and returns a `documentId`. Use this ID as the `uploadedDocumentId` field when calling `POST /v1/document/analyze`. Accepted formats: PDF, TXT, Markdown, CSV, JSON. Maximum file size: 20 MB.

Parameters

Name	Type	Description
fileRequired	binary (multipart/form-data)	The document file to upload. Must be sent as multipart/form-data with the field name `file`.

Requires the `document:upload` scope on your API key. The returned `id` is the `uploadedDocumentId` required by `POST /v1/document/analyze`.

cURL Example

curl -X POST "https://docology.hildebrandligtas.com/api/v1/document/upload" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "data": {
    "id": "clxyz123abc",
    "fileName": "annual_report_2025.pdf",
    "fileSize": 2456789,
    "status": "PENDING",
    "createdAt": "2026-05-06T10:00:00Z"
  },
  "message": "Document uploaded successfully"
}

POST/v1/document/analyze

Queue AI analysis for a document

Queues an AI-powered analysis job for a previously uploaded document. This is an asynchronous operation — the result is delivered via webhook (`analysis.created` event) when complete. Upload your document first using `POST /v1/document/upload` to obtain a `uploadedDocumentId`.

Parameters

Name	Type	Description
uploadedDocumentIdRequired	string	The `id` returned by `POST /v1/document/upload`. The document must belong to the API key owner.
inputText	string	Custom instructions for the AI analyzer. Max 2000 characters.
overrideDefaultSections	boolean	If true, only the custom instructions will be used.
analysisSource	string	A label to categorize the analysis source (e.g., "MARKETING", "FINANCE").

The analysis typically takes between 15-60 seconds depending on the document size and complexity.

cURL Example

curl -X POST "https://docology.hildebrandligtas.com/api/v1/document/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "uploadedDocumentId": "clxyz123abc",
  "inputText": "Extract financial data and summarize risks.",
  "overrideDefaultSections": false,
  "analysisSource": "GENERIC_BUSINESS"
}'

Request Body

{
  "uploadedDocumentId": "clxyz123abc",
  "inputText": "Extract financial data and summarize risks.",
  "overrideDefaultSections": false,
  "analysisSource": "GENERIC_BUSINESS"
}

Response Example

{
  "data": {
    "uploadedDocumentId": "clxyz123abc",
    "analysisId": "res_987654321"
  },
  "message": "Analysis queued"
}

GET/v1/document

List Documents

Returns a paginated list of all documents owned by the API key. Use `page` and `limit` query parameters to paginate through results.

Parameters

Name	Type	Description
page	number	Page number, starting at 1 (default: 1).
limit	number	Number of results per page (default: 20, max: 100).

Requires the `pdf:read` scope on your API key.

cURL Example

curl -X GET "https://docology.hildebrandligtas.com/api/v1/document" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "data": {
    "items": [
      {
        "id": "clxyz123abc",
        "fileName": "annual_report_2025.pdf",
        "fileSize": 2456789,
        "status": "DONE",
        "createdAt": "2026-05-06T10:00:00Z"
      },
      {
        "id": "clxyz456def",
        "fileName": "contract_q2.pdf",
        "fileSize": 1048576,
        "status": "PENDING",
        "createdAt": "2026-05-05T08:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

GET/v1/analysis

List Analyses

Returns a paginated list of all analysis results owned by the API key, ordered by creation date descending.

Parameters

Name	Type	Description
page	number	Page number, starting at 1 (default: 1).
limit	number	Number of results per page (default: 20, max: 100).

Requires the `pdf:read` scope on your API key.

cURL Example

curl -X GET "https://docology.hildebrandligtas.com/api/v1/analysis" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "data": {
    "items": [
      {
        "id": "res456",
        "pdfDocumentId": "clxyz123abc",
        "content": "The company showed a 15% increase in revenue...",
        "inputText": null,
        "createdAt": "2026-05-06T14:55:00Z"
      },
      {
        "id": "res789",
        "pdfDocumentId": "clxyz456def",
        "content": "Key risks include market volatility...",
        "inputText": "Summarize risk factors",
        "createdAt": "2026-05-05T09:10:00Z"
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 20
  }
}

GET/v1/document/:id

Get a Document

Retrieves the metadata and current status of a document by its unique ID.

Parameters

Name	Type	Description
idRequired	string	The unique ID of the document.

cURL Example

curl -X GET "https://docology.hildebrandligtas.com/api/v1/document/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "status": "success",
  "data": {
    "id": "doc_123456789",
    "fileName": "annual_report_2025.pdf",
    "fileSize": 2456789,
    "status": "UPLOADED",
    "createdAt": "2026-05-06T10:00:00Z"
  }
}

GET/v1/analysis/:id

Get an analysis result

Retrieves the full AI analysis results for a document. If the analysis is still in progress, it will return the current status.

Parameters

Name	Type	Description
idRequired	string	The unique ID of the analysis job.

cURL Example

curl -X GET "https://docology.hildebrandligtas.com/api/v1/analysis/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "status": "success",
  "data": {
    "id": "analysis_456789",
    "documentId": "pdf_123456789",
    "results": [
      {
        "section": "Financial Summary",
        "content": "The company showed a 15% increase in revenue...",
        "confidence": 0.98
      },
      {
        "section": "Risk Factors",
        "content": "Key risks include market volatility and supply chain...",
        "confidence": 0.92
      }
    ],
    "status": "COMPLETED",
    "completedAt": "2026-05-06T14:55:00Z"
  }
}