API
Use the HTTP API to validate configuration, load records, run searches, delete records, and check long-running jobs.
Contract status
The OpenAPI 3.1 document is the machine-readable source for this evolving alpha interface. The documented server name is the planned hosted endpoint; a self-hosted or private-preview deployment supplies its own base URL.
All tenant-scoped operations use bearer authentication and an X-CoreC-Tenant-Id header established by the trusted authentication boundary. State-changing operations also require a caller-generated Idempotency-Key.
Operations
| Method and path | Operation | Result |
|---|---|---|
| GET /healthz | health | Process health |
| POST /v1/configurations:validate | validateConfiguration | Validation result without applying state |
| POST /v1/corpora | applyCorpus | Applied immutable corpus revision |
| GET /v1/corpora/{corpusId} | getCorpus | Corpus state and active index versions |
| POST …/ingestion-batches:validate | validateIngestionBatch | Identity, provenance, access, and integrity checks |
| POST …/ingestion-batches | applyIngestionBatch | Durable asynchronous ingestion job |
| POST /v1/corpora/{corpusId}/records:delete | deleteRecords | Deletion-propagation job |
| POST /v1/corpora/{corpusId}/query | queryCorpus | Ranked evidence and optional synthesis-hook request |
| GET /v1/jobs/{jobId} | getJob | Pending, running, succeeded, failed, or cancelled state |
Validate a corpus configuration
Validation is intentionally unauthenticated in the alpha contract and does not apply state. The response contains valid plus path-addressed violations.
POST /v1/configurations:validate HTTP/1.1
Host: api.corecortex.io
Content-Type: application/json
{
"apiVersion": "corecortex.io/v1alpha1",
"kind": "Corpus",
"metadata": {"name": "knowledge-operations", "tenant": "example", "environment": "development"},
"spec": {"datasets": [], "storage": {}, "indexes": [], "retrievalPlans": []}
}Apply a prepared ingestion batch
Each request carries at most 1,000 canonical records. A successful apply returns HTTP 202 and a durable Job. Poll the job until it reaches a terminal state and retain its projection evidence with the corpus configuration.
POST /v1/corpora/{corpusId}/datasets/{datasetId}/ingestion-batches HTTP/1.1
Authorization: Bearer <token>
X-CoreC-Tenant-Id: <tenant-uuid>
Idempotency-Key: change-records-2026-08-26-part-1
Content-Type: application/json
{
"apiVersion": "corecortex.io/ingestion/v1alpha1",
"batchId": "change-records-2026-08-26",
"dataset": "change-records",
"configurationRevision": 4,
"mappingFingerprint": "<sha256>",
"source": {"format": "jsonl", "sha256": "<sha256>", "rows": 2400},
"part": {"number": 1, "total": 3},
"recordsSha256": "<sha256>",
"records": []
}Query contract
- POST /v1/corpora/{corpusId}/query runs the named retrieval plan.
- The response includes record, passage, dataset, source, request, and trace identity.
- Intent and filters can narrow retrieval scope; authenticated access remains authoritative.
Errors and retries
Errors use application/problem+json with type, title, HTTP status, stable code, requestId, traceId, and optional path violations. A 409 identifies an idempotency or immutable-state conflict. Retry asynchronous reads and transient transport failures with backoff; reuse the original idempotency key for a safe replay of the same write.