Alchimista - API Guide

Ingest · GCS Connector · Query · Decisions · Governance · Health

POST /v1/ingest

ingestion-api-service · port 8011

Submit a document for ingestion. Creates a job record and publishes to Pub/Sub for async processing.

Request Body

{
  "tenant":     "acme-corp",       // required — tenant identifier
  "source_uri": "gs://bucket/doc.pdf",  // required — GCS URI or HTTPS URL
  "doc_type":   "regulation",      // optional
  "metadata":   {}                 // optional — arbitrary key/value pairs
}

Response 202

{
  "job_id":  "job_abc123",
  "status":  "QUEUED",
  "tenant":  "acme-corp"
}

Poll GET /v1/doc/{job_id} to track processing. Status transitions: QUEUED → PROCESSING → SUCCEEDED | FAILED

GET /v1/doc/{id}

ingestion-api-service · port 8011

Get document and job status. Poll this endpoint after submitting an ingest job.

Response 200

{
  "job_id":      "job_abc123",
  "status":      "SUCCEEDED",       // QUEUED | PROCESSING | SUCCEEDED | FAILED
  "tenant":      "acme-corp",
  "source_uri":  "gs://bucket/doc.pdf",
  "chunk_count": 42,
  "updated_at":  "2025-03-01T12:00:00Z",
  "error":       null
}

POST /v1/connectors/gcs/import

ingestion-api-service · port 8011

Bulk-import all objects from a GCS bucket (optionally filtered by prefix). Each object is enqueued as an individual ingest job.

Request Body

{
  "tenant":   "acme-corp",         // required
  "bucket":   "my-docs-bucket",    // required — bucket name (no gs:// prefix)
  "prefix":   "regulations/2025/", // optional
  "doc_type": "regulation"         // optional
}

Response 202

{
  "jobs_queued": 47,
  "tenant":      "acme-corp",
  "bucket":      "my-docs-bucket"
}

POST /v1/query

rag-query-service · port 8013

Execute a retrieval-augmented generation query. Returns a natural language answer grounded in indexed document chunks, with mandatory citations.

Request Body

{
  "tenant":  "acme-corp",          // required
  "query":   "What does Art. 9 EU AI Act require?",  // required
  "k":       5,                    // optional — top-k chunks (default 5)
  "filters": {}                    // optional — metadata filters
}

Response 200

{
  "answer":   "High-risk AI systems must implement a risk management system...",
  "trace_id": "trace_xyz789",
  "citations": [
    { "doc_id": "doc_abc", "chunk_id": "chunk_7", "score": 0.94 },
    { "doc_id": "doc_def", "chunk_id": "chunk_2", "score": 0.87 }
  ]
}

The trace_id can be used to register a decision with POST /v1/decisions, linking the answer to its citations in the immutable audit trail.

Decision Trail API

rag-query-service · port 8013 · All decision records are immutable (write-once)

POST /v1/decisions Register an AI decision (write-once, returns 409 on duplicate trace_id)

{
  "tenant":        "acme-corp",
  "trace_id":      "trace_xyz789",   // unique identifier — 409 on reuse
  "decision_type": "rag_answer",
  "subject_id":    "user_456",       // optional
  "citations":     [{"doc_id":"doc_abc","chunk_id":"chunk_7","score":0.94}],
  "context":       {"query":"...","answer":"...","model":"gemini-1.5-pro"},
  "metadata":      {}
}

POST /v1/decisions/query Search registered decisions

{
  "tenant":        "acme-corp",
  "trace_id":      "trace_xyz789",   // optional filter
  "subject_id":    "user_456",       // optional filter
  "decision_type": "rag_answer",     // optional filter
  "from_date":     "2025-01-01",     // optional
  "to_date":       "2025-12-31",     // optional
  "limit":         50
}

GET /v1/decisions/report?tenant=&from_date=&to_date= Compliance summary report

POST /v1/decisions/export Export decision bundle

POST /v1/decisions/bundle Create immutable artifact

POST /v1/decisions/package Package for compliance submission

POST /v1/decisions/verify Verify artifact integrity (checksum)

Governance API

rag-query-service · port 8013 · Requires x-admin-key header

Retention Policies

POST /v1/admin/retention-policies Create policy

GET /v1/admin/retention-policies?tenant= List policies

DELETE /v1/admin/retention-policies/{id} Delete policy

{
  "tenant":         "acme-corp",
  "policy_name":    "gdpr-7-year",
  "retention_days": 2555,           // 7 × 365
  "doc_types":      ["regulation", "directive"],  // optional
  "action":         "delete"        // delete | archive
}

Legal Holds

POST /v1/admin/legal-holds Create hold — prevents retention deletion

GET /v1/admin/legal-holds?tenant= List holds

DELETE /v1/admin/legal-holds/{id} Release hold

Enforcement

POST /v1/admin/retention/enforce Run enforcement pass

{
  "tenant":   "acme-corp",
  "dry_run":  true    // false = permanent deletion; always test with dry_run=true first
}

Health Endpoints

All services expose GET /v1/healthz — returns 200 when healthy

Service	Endpoint	Port
ingestion-api-service	`GET /v1/healthz`	8011
document-processor-service	`GET /v1/healthz`	8012
rag-query-service	`GET /v1/healthz`	8013
Dashboard aggregate	`GET /api/v1/health`	8000

API Reference

Decision Trail API

Governance API

Health Endpoints