Partner API Reference

Introduction

Document Gateway is the clearinghouse for an organization’s documents of record — it ingests, certifies, vaults, classifies, abstracts, and tracks compliance for every document across its lifecycle. The Partner API is the programmatic surface over that whole platform: an external system — your DMS, data warehouse, ERP/CLM, analytics platform, or workflow engine — can push documents in, read any part of the record (documents & storage, vault & certificates, compliance, connectors & hierarchy, audit trail, plus AI abstracts), search, and react to events in real time.

The API spans the platform’s domains, not a single feature:

Document intelligence (abstracts/families) is one domain among several — see Platform resources for the full catalog and Ingest to push documents in.

Quickstart

1 · Get an API key

In Gateway, open API Marketplace → API Keys and issue a partner key. The key is shown once — store it securely. Keys are prefixed aidi_ and carry a set of scopes.

2 · Make your first call

# Confirm your key and see its scopes
curl https://nwbjvdemkdvlzdbntgnd.supabase.co/functions/v1/partner-api/v1/me \
  -H "Authorization: Bearer aidi_YOUR_KEY"

// 200 OK
{ "key_id": "8853f747-…", "scopes": ["abstracts:read","families:read","documents:read","search","webhooks:manage"], "tenant_id": null }

3 · Pull your abstracts

curl ".../partner-api/v1/abstracts?limit=10" \
  -H "Authorization: Bearer aidi_YOUR_KEY"

Data-science quickstart

The thing that sets AI.DI apart: you don’t just get documents and metadata — you get the real intelligence. AI.DI abstracts any document, in any industry — contracts, agreements, invoices, policies, regulatory filings, certificates, HR records, financial statements — into structured fields, key clauses, and risk flags. In about a minute you can pull that intelligence into a pandas DataFrame and build on it.

From zero to a DataFrame of document intelligence

# pip install requests pandas
import requests, pandas as pd

API = "https://nwbjvdemkdvlzdbntgnd.supabase.co/functions/v1/partner-api"
H   = {"Authorization": "Bearer aidi_YOUR_KEY"}

# 1 · Pull abstracts — each includes the FULL extracted intelligence
#     (field_groups, key_clauses, risk_flags), not just metadata.
abstracts = requests.get(f"{API}/v1/abstracts?limit=100", headers=H).json()["data"]

# 2 · Flatten every extracted field into a tidy DataFrame
rows = [
  {"document": a["file_name"], "doc_type": a.get("document_type"),
   "group": g.get("group"), "field": f.get("label"), "value": f.get("value")}
  for a in abstracts
  for g in a.get("field_groups", [])
  for f in g.get("fields", [])
]
df = pd.DataFrame(rows)

# 3 · Now query the intelligence like any dataset — pivot, filter, join, model
expirations = df[df.field.str.contains("Expiration", case=False, na=False)]
print(expirations.head())
# → any extracted field, across every document type, in one frame.

Ask in natural language (semantic search)

# Meaning-based search across the abstract intelligence — any document type
hits = requests.post(f"{API}/v1/search", headers=H, json={
  "query": "agreements with an auto-renewal clause expiring in 2026",
  "limit": 20,
}).json()["data"]

Connect an AI agent (MCP)

AI.DI ships a built-in MCP server — the same intelligence exposed as 24 tools any AI agent can call. Connect Claude (claude.ai one-click OAuth 2.1 connector, Claude Code, or Claude Desktop), ChatGPT (GPT Actions), or your own Python / LangChain agent — all from one workspace-scoped key. Read-only, RLS-enforced, scoped to your data.

The toolset spans the whole platform — get_abstract (a document’s full field groups, clauses & risk flags), query_abstract_fields (query extracted fields across every document at once), get_family_abstract (rolled-up terms for a grouped document set, e.g. a contract and its amendments), plus search, compliance, obligations, anomalies, expirations, and more. Mint an agent key in Warehouse → API Keys → Connect Claude, then point any MCP client at:

https://nwbjvdemkdvlzdbntgnd.supabase.co/functions/v1/mcp-server/mcp   # Bearer dg_agent_YOUR_KEY

# Claude Code — one command:
claude mcp add aidi --transport http .../functions/v1/mcp-server/mcp \
  --header "Authorization: Bearer dg_agent_YOUR_KEY"

What you can build on top of AI.DI

Because the structured intelligence is an API, your data scientists and product teams can build directly on it — no document parsing, no model to train:

• Analytics & dashboards — turn any document set into a queryable dataset: registries, obligation calendars, expirations, exposure, KPIs — straight from the abstract fields.
• Models & pipelines — feed clean document features into your own models in Snowflake, Databricks, or a notebook — no parsing, no model to train.
• Agents & copilots — attach Claude or ChatGPT and let it answer in natural language over your real documents, grounded and cited.
• Apps & extensions — embed AI.DI intelligence into the systems your clients already run (ERP, CLM, ICM, BI), or ship a new product on top of it.
• Event-driven workflows — subscribe to abstract.completed webhooks and trigger downstream automation the moment a document is understood.

Authentication & scopes

Every request (except the public OpenAPI spec) must include a bearer token:

Authorization: Bearer aidi_YOUR_KEY

Keys are stored only as SHA-256 hashes — Gateway cannot recover a lost key; rotate it (revoke + reissue) instead. Each key is authorized for a set of scopes; a call to an endpoint outside the key's scopes returns 403 forbidden.

Key & secret lifecycle

There are two secrets in an integration: your API key (you send it on every request) and a webhook signing secret (we use it to sign callbacks to you). Both are shown exactly once and stored only as hashes/secrets on our side — treat them like passwords.

Base URL & format

https://nwbjvdemkdvlzdbntgnd.supabase.co/functions/v1/partner-api

All responses are JSON. Successful resource responses wrap the payload in data; list responses add a pagination object. All timestamps are ISO-8601 UTC.

Pagination

List endpoints accept limit (1–100, default 25) and offset (default 0), and return a pagination block with the exact total count.

{
  "data": [ … ],
  "pagination": { "limit": 25, "offset": 0, "total": 74, "returned": 25 }
}

For incremental sync, page by created_at using the since filter on /v1/abstracts rather than deep offsets.

Errors

Errors use standard HTTP status codes and a consistent envelope:

{ "error": { "code": "forbidden", "message": "Key lacks scope abstracts:read" } }

Rate limits & versioning

Be a good citizen: keep sustained traffic under ~120 requests/minute per key and use the since cursor instead of polling full lists. The API is versioned in the path (/v1/…); breaking changes ship under a new version and the previous version remains available during a deprecation window announced in the changelog.

Identity

Abstracts

An abstract is the structured extraction of a single document: typed fields grouped by section, risk flags, key clauses, a summary, and provenance. See the Abstract object reference.

curl ".../v1/abstracts?document_type=Absolute%20Net%20Lease%20Agreement&limit=2" \
  -H "Authorization: Bearer aidi_YOUR_KEY"

{
  "data": [
    { "id": "…", "file_name": "Lease Agreement Fetna - 599.pdf",
      "document_type": "Absolute Net Lease Agreement",
      "document_family_key": "grange conglomerate inc|100 hayden avenue…",
      "total_fields": 142, "created_at": "2026-06-22T11:25:40Z" }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 74, "returned": 2 }
}

{ "id": "…", "file_name": "Lease Agreement Fetna - 599.pdf",
  "file_type": "application/pdf",
  "download_url": "https://…signed…", "expires_in": 900 }

Families

A family groups a primary document with its amendments, SNDAs, and related instruments (e.g. a lease and everything that modifies it). Members are deduplicated to the most recent abstract per source document and ordered by effective date.

curl ".../v1/families/grange%20conglomerate%20inc%7C100%20hayden%20avenue…" \
  -H "Authorization: Bearer aidi_YOUR_KEY"

{ "data": {
    "family_name": "Grange conglomerate inc | 100 Hayden Avenue…",
    "family_type": "lease", "member_count": 2,
    "members": [
      { "file_name": "Lease Agreement Fetna - 599.pdf", "sequence_role": "original" },
      { "file_name": "SNDA and Amendment… - 600.pdf", "sequence_role": "amendment" }
    ] } }

Rendered documents

Pull the actual rendered files behind an abstract or family — not just the extracted data — as short-lived signed download URLs. Generated on demand (or reused if already rendered): the source Lease Abstract, an Excel workbook of the same, an Audit Exceptions workbook, and the Hawkeye Audit Report.

curl ".../v1/abstracts/{id}/pdf?kind=audit" \
  -H "Authorization: Bearer aidi_YOUR_KEY"

{ "abstract_id": "…", "family_key": "…", "kind": "audit",
  "content_type": "application/pdf", "download_url": "https://…signed…", "expires_in": 900 }

{ "abstract_id": "…", "family_key": "…",
  "documents": [
    { "kind": "abstract", "label": "Lease Abstract", "content_type": "application/pdf", "download_url": "…", "expires_in": 900 },
    { "kind": "exceptions", "error": "No saved ERP audit for this family" }
  ] }

Search

curl -X POST ".../v1/search" \
  -H "Authorization: Bearer aidi_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"query":"rent escalation in net leases","limit":5}'

Platform resources

Beyond abstracts, the API exposes read access to the rest of the document-of-record platform. Every resource below follows the same shape: GET /v1/{resource} (paginated list with the standard limit/offset + the filters noted) and GET /v1/{resource}/{id} (single record). All return the { data, pagination } envelope and honor your key's scopes and tenant binding. Sample/demo records are never returned.

Documents & storage — scope documents:read

Vault & certification — scope vault:read

Compliance — scope compliance:read

Connectors & hierarchy — scope connectors:read

Access & audit — scope audit:read

Reports — scope reports:read

Reports (rent rolls, arrears, trial balances, P&L) ride the same submission rails as documents — validated, QC'd, and cross-referenced against the document set, not just stored files.

Ingest a document (write)

Push a file into Gateway. The bytes run the full ingest pipeline — SHA-256 hash, exact-duplicate check, text extraction, fuzzy fingerprinting, tiered storage, and record creation — and fire the document.ingested webhook. This is the only write endpoint; it needs the dedicated documents:write scope, which you grant deliberately (it is not in the default read-only key).

Ingest is asynchronous: the call returns 202 Accepted right away and the pipeline runs in the background. You get the final document_id, content_hash, and result from the document.ingested webhook (or by polling GET /v1/documents) — not in the immediate response.

Large files — upload directly to storage (recommended)

Do not send multi-MB files as base64 inside the JSON body — large request bodies do not pass reliably through the API gateway (you may see a 504). Instead, upload the raw bytes straight to storage with a short-lived signed URL, then start ingest with just the path. Three steps:

1. Ask for a signed upload URL (tiny request):

curl -X POST ".../v1/documents/upload-url" \
  -H "Authorization: Bearer aidi_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"file_name":"lease.pdf","mime_type":"application/pdf"}'

// 200 OK
{ "data": { "upload_url": "https://…/storage/v1/object/upload/sign/…?token=…",
  "storage_path": "partner-ingest/…/lease.pdf",
  "method": "PUT", "headers": { "Content-Type": "application/pdf", "x-upsert": "true" } } }

2. PUT the raw file bytes to upload_url (this goes directly to storage and bypasses the API gateway — no size problem):

curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" -H "x-upsert: true" \
  --data-binary "@lease.pdf"

3. Start ingest with the returned storage_path:

curl -X POST ".../v1/documents" \
  -H "Authorization: Bearer aidi_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"storage_path":"partner-ingest/…/lease.pdf","file_name":"lease.pdf","mime_type":"application/pdf"}'

// 202 Accepted — ingest runs asynchronously
{ "data": { "status": "processing", "storage_path": "partner-ingest/…/lease.pdf",
  "file_name": "lease.pdf", "file_size": 123456 } }

Small files — inline base64 (≤ 6 MB)

For small files you can skip the signed-URL step and inline the bytes directly. Same async 202 response as above.

curl -X POST ".../v1/documents" \
  -H "Authorization: Bearer aidi_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"file_name":"lease.pdf","mime_type":"application/pdf","file_base64":"JVBERi0x..."}'

Webhooks — events & payloads

Subscribe to events instead of polling. Gateway POSTs a signed JSON payload to your URL when an event fires.

Delivery payload:

{
  "event": "abstract.completed",
  "delivery_id": "f1e2…",
  "created_at": "2026-06-22T12:30:00Z",
  "data": { "job_id": "…", "abstract_ids": ["…","…"], "count": 2 }
}

Headers on every delivery:

Managing webhooks

curl -X POST ".../v1/webhooks" \
  -H "Authorization: Bearer aidi_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://your-system.example.com/imkore","events":["abstract.completed"]}'

Verifying signatures

Recompute the HMAC-SHA256 of "{X-Imkore-Timestamp}.{rawRequestBody}" using your webhook secret, then constant-time compare it to the hex in X-Imkore-Signature. Reject if it doesn't match or the timestamp is stale (> 5 min).

// Node.js (Express)
import crypto from 'crypto';
function verify(req, secret) {
  const ts  = req.headers['x-imkore-timestamp'];
  const sig = req.headers['x-imkore-signature'].replace('sha256=', '');
  const mac = crypto.createHmac('sha256', secret)
                   .update(ts + '.' + req.rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
}

# Python (Flask)
import hmac, hashlib
def verify(headers, raw_body, secret):
    ts  = headers['X-Imkore-Timestamp']
    sig = headers['X-Imkore-Signature'].replace('sha256=', '')
    mac = hmac.new(secret.encode(), f"{ts}.{raw_body}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

Abstract object

OpenAPI spec

A machine-readable OpenAPI 3.1 document is served (no auth) for code generation and import into Postman / Insomnia / Swagger UI:

GET https://nwbjvdemkdvlzdbntgnd.supabase.co/functions/v1/partner-api/openapi.json

Support & changelog

Questions, key provisioning, or tenant scoping: contact your imkore representative or developers@imkore.com.