Skip to content

API Reference

The 6 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 use NodePort URLs (localhost:3000X) for local Docker Desktop K8s development — direct access to services for debugging.

In production, all requests go through Kong APIM (https://api.djinn.solyntek.io), which handles API key authentication, rate limiting and routing to internal services. Services are never exposed directly in production (ClusterIP only). See the internal documentation (Kong APIM, ADR-013).

Kong AI Gateway (Phase 3)

Starting with Phase 3, LLM routing will be handled by the Kong AI Gateway plugins (ai-proxy, ai-prompt-template, etc.) to centralize prompts and multi-provider fallback. See ADR-014 (internal documentation).

Getting Started

1. Base URL

All requests go through the Kong gateway:

https://api.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.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 (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.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",
    "total_ht": 1250.00,
    "total_ttc": 1500.00,
    "vat_amount": 250.00,
    "iban": "FR7630001007941234567890185"
  },
  "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

    Port 8000 · NodePort 30002

  • Candidate Analyzer

    POST /v1/analyze — Candidate scoring vs job postings

    Port 8003 · NodePort 30003

  • AI Assistant

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

    Port 8004 · NodePort 30004

  • Export Hub

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

    Port 8005 · NodePort 30005

  • Audit Trail

    POST /v1/events — GDPR audit log

    Port 8006 · NodePort 30006

  • Company Verifier

    GET /v1/companies/{siren}/compliance

    Port 8007 · NodePort 30007

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

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).