API Docs — Perceptiq Analytics

Quickstart

1. Create an API key

API keys are issued after access approval. Your key is shown once and starts with pa_live_.

POST /api/access/request
POST /api/access/enable   (admin only)

Store keys in a secret manager. Never expose them in frontend code.

2. Make your first API call

curl "http://127.0.0.1:8100/v1/summary" ^
  -H "Authorization: Bearer <API_KEY>"

import requests

BASE_URL = "http://127.0.0.1:8100"
API_KEY = "pa_live_..."

res = requests.get(
    f"{BASE_URL}/v1/summary",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
print(res.json())

const BASE_URL = "http://127.0.0.1:8100";
const API_KEY = "pa_live_...";

const res = await fetch(`${BASE_URL}/v1/summary`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const data = await res.json();
console.log(data);

3. Upload then ask questions

curl -X POST "http://127.0.0.1:8100/v1/upload?merge=true" ^
  -H "Authorization: Bearer <API_KEY>" ^
  -F "files=@contract.pdf"

curl -X POST "http://127.0.0.1:8100/v1/ask" ^
  -H "Authorization: Bearer <API_KEY>" ^
  -H "Content-Type: application/json" ^
  -d "{\"question\":\"What are the renewal and termination clauses?\"}"

import requests

BASE_URL = "http://127.0.0.1:8100"
headers = {"Authorization": "Bearer pa_live_..."}

with open("contract.pdf", "rb") as f:
    requests.post(f"{BASE_URL}/v1/upload?merge=true", headers=headers, files={"files": f})

answer = requests.post(
    f"{BASE_URL}/v1/ask",
    headers={**headers, "Content-Type": "application/json"},
    json={"question": "What are the renewal and termination clauses?"}
)
print(answer.json())

const BASE_URL = "http://127.0.0.1:8100";
const headers = { Authorization: "Bearer pa_live_..." };

const form = new FormData();
form.append("files", fileInput.files[0]);
await fetch(`${BASE_URL}/v1/upload?merge=true`, { method: "POST", headers, body: form });

const askRes = await fetch(`${BASE_URL}/v1/ask`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ question: "What are the renewal and termination clauses?" })
});
console.log(await askRes.json());

Function-style API map

Use endpoints like callable functions:

uploadDocuments(files)

POST /v1/upload

Scope: upload

getProcessingStatus()

GET /v1/status

Scope: status

listDocuments()

GET /v1/documents

Scope: documents

askQuestion(question)

POST /v1/ask

Scope: ask

getSummary(docId?)

GET /v1/summary

Scope: summary

listTemplates()

GET /v1/templates

Scope: templates

generateTemplate(body)

POST /v1/templates/generate

Scope: templates

smartExtract(payload)

POST /v1/templates/smart/extract

Scope: templates

smartExtractBatch(items)

POST /v1/templates/smart/extract/batch

Scope: templates

searchDocuments(q, docId?)

GET /v1/search

Scope: search

exportData(scope, format)

GET /v1/export

Scope: export

autoTagText(payload)

POST /v1/tagging

Scope: tagging

compareDocs(baseId, compareId)

POST /v1/compare

Scope: compare

getDashboardMetrics()

GET /v1/dashboard/metrics

Scope: metrics

Enablement syntax

curl -X POST "http://127.0.0.1:8100/api/access/request" ^
  -H "Content-Type: application/json" ^
  -d "{\"full_name\":\"John Doe\",\"email\":\"john@company.com\",\"company\":\"Company Inc\",\"requested_tier\":\"growth\",\"use_case\":\"Integrate analysis workflow\",\"expected_monthly_documents\":2500}"

Admin lifecycle syntax

curl -X POST "http://127.0.0.1:8100/api/access/enable" ^
  -H "x-admin-token: <API_ADMIN_TOKEN>" ^
  -H "Content-Type: application/json" ^
  -d "{\"email\":\"john@company.com\",\"company\":\"Company Inc\",\"tier\":\"growth\",\"rate_limit_rpm\":180}"

curl -X POST "http://127.0.0.1:8100/api/access/rotate" ^
  -H "x-admin-token: <API_ADMIN_TOKEN>" ^
  -H "Content-Type: application/json" ^
  -d "{\"client_id\":\"cli_abc123def456\",\"reason\":\"Quarterly rotation\"}"

Smart extraction syntax

curl -X POST "http://127.0.0.1:8100/v1/templates/smart/extract" ^
  -H "Authorization: Bearer <API_KEY>" ^
  -H "Content-Type: application/json" ^
  -d "{\"ocr_tokens\":[{\"text\":\"Invoice #\",\"bbox\":[0.11,0.14,0.09,0.02],\"page\":1},{\"text\":\"INV-123\",\"bbox\":[0.21,0.14,0.10,0.02],\"page\":1}],\"document_text\":\"\",\"document_images\":[],\"top_k_templates\":3}"

Scope by plan

API scopes are granted by tier and can be customized during enablement.

Tier	Default scopes
Starter	`status, documents, summary, search, export`
Growth	Starter + `upload, ask, templates, tagging`
Business / Enterprise	Growth + `compare, metrics, summary_audio`

Perceptiq API access, enablement, and syntax