Developer API Documentation

Authentication

All endpoints of the DocuSense AI API are secure and require a Bearer token authorization header. API requests are mapped directly to your active Workspace context.

Acquiring an API Key

Log in, navigate to Workspace Settings in your dashboard, select the API Access tab, and click Generate Key. Make sure your workspace is subscribed to a plan that supports API access.

Provide your secret API Key inside the standard HTTP Authorization header on all request payloads:

Authorization: Bearer ds_live_...

Credits & Billing Limits

Developer API requests consume workspace credits dynamically, guaranteeing pay-as-you-go consistency with your standard subscriptions:

Document Uploads: Consumes credits according to the file size (1 credit per MB, rounded up).
RAG & AI Chat Queries: Consumes credits based on total generated words (1 credit per 1,000 generated words).
Metadata Queries & Deletions: These actions are completely Free and consume 0 credits.

Error Handling

Standard HTTP status codes are used by the API to denote execution results:

Status	Meaning	Typical Cause
200 / 201	OK / Created	Request completed successfully.
400	Bad Request	Target document is still processing or parsing failed.
401	Unauthorized	API key is missing, invalid, or revoked.
402	Payment Required	Active workspace has run out of credits. Please purchase top-ups.
403	Forbidden	Your active workspace plan does not support developer API access.
404	Not Found	Target document or resource does not exist in your workspace.
422	Unprocessable Entity	Validation failed (e.g. invalid file mimetype or missing query message).

GET

Retrieve Workspace Info

/api/v1/workspace

Fetches comprehensive metrics regarding your developer environment, including remaining credits, owner, and total workspace documents.

Request Example

curl -X GET "https://meg-docusenseai.onecrib.com/api/v1/workspace" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

fetch('https://meg-docusenseai.onecrib.com/api/v1/workspace', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/workspace");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/workspace"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Acme Development",
    "credits_remaining": 4850,
    "owner": "John Doe",
    "documents_count": 14
  }
}

GET

List Documents

/api/v1/documents

Returns a paginated list of all active files and documents within your active workspace, including parsing statuses.

Request Example

curl -X GET "https://meg-docusenseai.onecrib.com/api/v1/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

fetch('https://meg-docusenseai.onecrib.com/api/v1/documents', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/documents");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/documents"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": 12,
      "title": "Annual_Report_2025",
      "original_filename": "Annual_Report_2025.pdf",
      "mime_type": "application/pdf",
      "file_size": 240500,
      "page_count": 18,
      "status": "ready",
      "created_at": "2026-05-18T10:45:00.000000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

POST

Upload & Process Document

/api/v1/documents

Programmatically uploads and processes a document. The engine parses texts automatically, triggers OCR scanning for images, partitions contents, extracts vector embeddings, and stores RAG vectors immediately. Deducts credits synchronously based on file size.

Request Body (Multipart Form)

document (Required): The file content. Must be a PDF, DOCX, or TXT file (Max size: 50MB).

Request Example

curl -X POST "https://meg-docusenseai.onecrib.com/api/v1/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "document=@/path/to/file.pdf"

const formData = new FormData();
formData.append('document', fileInput.files[0]);

fetch('https://meg-docusenseai.onecrib.com/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  },
  body: formData
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/documents");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    "document" => new CURLFile("/path/to/file.pdf")
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/documents"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}
files = {
    "document": open("file.pdf", "rb")
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "message": "Document uploaded and processed successfully.",
  "data": {
    "id": 15,
    "title": "research",
    "original_filename": "research.pdf",
    "mime_type": "application/pdf",
    "file_size": 1520100,
    "page_count": 4,
    "status": "ready",
    "created_at": "2026-05-18T15:24:00.000000Z"
  }
}

GET

Get Document Details

/api/v1/documents/{document_id}

Fetches details, parsed page counts, status information, and error diagnostics for a target document resource.

Request Example

curl -X GET "https://meg-docusenseai.onecrib.com/api/v1/documents/15" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

fetch('https://meg-docusenseai.onecrib.com/api/v1/documents/15', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/documents/15");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/documents/15"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "data": {
    "id": 15,
    "title": "research",
    "original_filename": "research.pdf",
    "mime_type": "application/pdf",
    "file_size": 1520100,
    "page_count": 4,
    "status": "ready",
    "status_message": "Successfully parsed and generated vector indexes.",
    "created_at": "2026-05-18T15:24:00.000000Z"
  }
}

DELETE

Delete Document

/api/v1/documents/{document_id}

Revokes, un-indexes, and permanently purges a document, its extracted pages, vectors, and chat history. This action is irreversible.

Request Example

curl -X DELETE "https://meg-docusenseai.onecrib.com/api/v1/documents/15" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

fetch('https://meg-docusenseai.onecrib.com/api/v1/documents/15', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/documents/15");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/documents/15"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "message": "Document deleted successfully."
}

POST

Ask Document / Chat (RAG)

/api/v1/documents/{document_id}/chat

Interacts programmatically with a document through our RAG (Retrieval-Augmented Generation) pipeline. The query triggers an embedding vector match to score page content similarity, builds a contextual window, submits it to your active workspace LLM provider, saves conversation metrics, and returns the response with semantic page citations.

Request Body (JSON)

message (Required): The query or prompt (Max 2,000 characters). E.g. "What is the total revenue listed on page 2?".

Request Example

curl -X POST "https://meg-docusenseai.onecrib.com/api/v1/documents/15/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the key conclusions?"
}'

fetch('https://meg-docusenseai.onecrib.com/api/v1/documents/15/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "message": "What are the key conclusions?"
})
})
.then(res => res.json())
.then(data => console.log(data));

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://meg-docusenseai.onecrib.com/api/v1/documents/15/chat");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(array (
  'message' => 'What are the key conclusions?',
)));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

import requests

url = "https://meg-docusenseai.onecrib.com/api/v1/documents/15/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
}
payload = {
    "message": "What are the key conclusions?"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response Example (200 OK)

{
  "status": "success",
  "data": {
    "response": "The key conclusions of the report are: \n1. Q3 revenue grew by 24% through workflows.\n2. Operating margins optimized by 12%.",
    "citations": [
      {
        "page": 4,
        "snippet": "We conclude that operations expanded our profitability margin by 12% in the second segment..."
      }
    ],
    "credits_used": 2
  }
}

Developer API Reference

Authentication

Acquiring an API Key

Credits & Billing Limits

Error Handling

API Endpoint Reference

Locating your Document ID ({document_id})

Retrieve Workspace Info

Request Example

Response Example (200 OK)

List Documents

Request Example

Response Example (200 OK)

Upload & Process Document

Request Body (Multipart Form)

Request Example

Response Example (200 OK)

Get Document Details

Request Example

Response Example (200 OK)

Delete Document

Request Example

Response Example (200 OK)

Ask Document / Chat (RAG)

Request Body (JSON)

Request Example

Response Example (200 OK)

Install DocuSense AI