Last update: October 15, 2026

API Reference¶

The 7 Djinn services expose REST APIs (FastAPI) with auto-generated Swagger documentation on each service (/docs).

Convention

All routes are prefixed with /v1/ (ADR-005). Authentication via the X-API-Key header.

Local vs Production

The examples in this documentation target production, through Kong APIM (https://api.dev.djinn.solyntek.io), which handles API key authentication, rate limiting and routing to the services. In production the services are reached only through the gateway: you need one URL and one key.

In the local Docker Compose stack, Kong listens on localhost:30080 and each service is also published on localhost:3000X (e.g. 30002 for doc-extract); a call straight to a service still requires a valid X-API-Key (no development key exists).

Kong AI Gateway

The LLM calls made by the services themselves go through the Kong AI Gateway plugins (ai-proxy, ai-prompt-template, ...), which centralise prompts and the provider. These routes are internal and are not part of the client API. See ADR-014 (internal documentation).

Getting Started¶

1. Base URL¶

All requests go through the Kong gateway:

https://api.dev.djinn.solyntek.io

Kong routes each /v1/... prefix to the corresponding internal service: you only need one URL and one key to manage, regardless of the service being called.

2. Authentication¶

Each tenant receives an API key (associated with a Kong consumer), to be passed in the X-API-Key header of every request:

curl https://api.dev.djinn.solyntek.io/v1/schemas \
  -H "X-API-Key: your-api-key"

Without a valid key, Kong responds with 401 Unauthorized before the request even reaches the service. Rate limiting is also applied per key (60 requests/minute and 1,000/hour; 429 Too Many Requests beyond the quota). See the Authentication guide.

3. First call: extract an invoice end-to-end¶

Extraction is synchronous: a single call is enough to send the file and retrieve the structured data.

curl -X POST https://api.dev.djinn.solyntek.io/v1/extract \
  -H "X-API-Key: your-api-key" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"

{
  "document_type": "invoice",
  "data": {
    "vendor_name": "Acme SARL",
    "invoice_number": "FA-2026-0042",
    "invoice_date": "2026-06-30",
    "subtotal": 1250.00,
    "vat_amount": 250.00,
    "total_amount": 1500.00,
    "currency": "EUR",
    "payment_reference": "FR7630001007941234567890185"
  },
  "text_source": "native_pdf",
  "confidence": 0.93
}

From there, the same JSON can feed the other services with the same key: generate an accounting export (POST /v1/export/fec), verify the supplier (GET /v1/companies/{siren}/compliance) — each call being logged in the audit trail (GET /v1/events).

4. Explore the APIs¶

Each service page below combines a route overview, curl examples and an interactive reference generated from the service's versioned OpenAPI spec.

Services¶

Doc Extract

POST /v1/extract — Invoices, resumes, ID documents

Local port 30002
Candidate Analyzer

POST /v1/analyze — Explainable decision support for recruitment

Local port 30003
AI Assistant

POST /v1/knowledge-bases/{id}/query — RAG chat

Local port 30004
Export Hub

POST /v1/export/fec — FEC, Sage, Pennylane, payroll

Local port 30005
Audit Trail

POST /v1/events — GDPR audit log

Local port 30006
Company Verifier

GET /v1/companies/{siren}/compliance

Local port 30007
Doc Trust

POST /v1/authenticity/analyze — Document authenticity opinion

Local port 30008

OpenAPI Specs¶

In accordance with ADR-011, each service's OpenAPI spec is exported from the code (app.openapi(), without starting a server) and committed to this repo — the single source of truth for third-party clients, with no need for access to the service repos.

Service	OpenAPI Spec
Doc Extract	`openapi/doc-extract-v1.json`
Candidate Analyzer	`openapi/candidate-analyzer-v1.json`
AI Assistant	`openapi/ai-assistant-v1.json`
Export Hub	`openapi/export-hub-v1.json`
Audit Trail	`openapi/audit-trail-v1.json`
Company Verifier	`openapi/company-verifier-v1.json`
Doc Trust	`openapi/doc-trust-v1.json`

MCP Gateway

The mcp-gateway service is a special case: it exposes the capabilities of the 6 services via the MCP protocol (Model Context Protocol) on the /mcp endpoint, for agents and MCP clients (rather than REST integrations). Built on FastMCP, it does not expose a FastAPI object and therefore has no OpenAPI spec — which is why it does not appear in the list above. See the MCP tool catalog in the internal documentation (architecture/mcp-gateway.md).

Regeneration: documentation/scripts/export_openapi.py (one run per service, from that service's venv — see the script's docstring).