HTTP route restructure under /v1

Relata DB 3.0
This describes 3.0 (change #5960). Versions up to 2.5.8 serve the old paths. The table of record is the source repository's API route map. The open build's OpenAPI document pins 222 paths (255 operations), and the server's GET /openapi.json is the contract.

The rules

  • Every public data-plane path moves under /v1/. This is a hard break: there are no aliases, and an old path answers 404.
  • Unchanged: probes and discovery (/health, /health/live, /health/ready, /version, /), POST /mcp, the OTLP routes /v1/traces, /v1/logs and /v1/metrics, and the loopback /admin/* listener.
  • /admin/* is served only on the loopback admin listener (default 127.0.0.1:9091), never on the data-plane port.
  • Names are plural kebab-case nouns, with a verb only as a trailing action (.../reactivate).
  • Enterprise-only route families are not compiled into the open build. See Editions.

Families that gained the prefix

For these families the new path is the old path with /v1 in front (for example POST /query becomes POST /v1/query, GET /objects/{type}/{id} becomes GET /v1/objects/{type}/{id}):

/a2a, /alerts, /assertions, /audit, /cluster, /commit, /embed, /entities, /evidence, /export, /files, /freshness, /gdpr, /graph, /graphql, /identity, /ingest, /jobs, /links, /lookup, /mcp, /media, /memory, /objects, /observe, /ontology, /query, /queues, /rag, /resolution, /retention, /rules, /schema, /search, /sequences, /tenants, /types, /watch

Some of these hold Enterprise-only members that are absent from the open build: /tenants administration, /cluster, and /audit/proof with /audit/export.

Renamed or relocated routes

Where the new path is not simply the old path with a prefix:

MethodOld pathNew path
GET/status/v1/system/status
GET/specs/v1/system/specs
POST/multi-search/v1/search/multi
GET/memory/recall_procedure/v1/memory/recall-procedure
POST/memory/remember_procedure/v1/memory/remember-procedure
GET/platform/license/admin/platform/license
GET/platform/tenants/admin/platform/tenants
POST/platform/tenants/admin/platform/tenants
GET/platform/tenants/{id}/admin/platform/tenants/{id}
DELETE/platform/tenants/{id}/admin/platform/tenants/{id}
POST/platform/tenants/{id}/reactivate/admin/platform/tenants/{id}/reactivate
POST/platform/tenants/{id}/suspend/admin/platform/tenants/{id}/suspend
PATCH/platform/tenants/{id}/tier/admin/platform/tenants/{id}/tier
GET/platform/usage/admin/platform/usage
GET/tokens/self/v1/auth/tokens/self
GET/tokens/self/audit/v1/auth/tokens/self/audit
POST/tokens/self/rotate/v1/auth/tokens/self/rotate
DELETE/tokens/self/{id}/v1/auth/tokens/self/{id}
POST/session/{id}/commit/v1/sessions/{id}/commit
GET/session/{id}/diff/v1/sessions/{id}/diff
DELETE/session/{id}/draft/v1/sessions/{id}/draft
GET/config/v1/system/config
GET/notifications/rules/v1/notification-rules
POST/notifications/rules/v1/notification-rules
PATCH/notifications/rules/{id}/v1/notification-rules/{id}
DELETE/notifications/rules/{id}/v1/notification-rules/{id}
GET/alerts/list/v1/alerts
POST/alerts/submit/v1/alerts
PATCH/alerts/update/{id}/v1/alerts/{id}
POST/internal/gdpr/dsar_shard/internal/gdpr/dsar-shard
POST/internal/gdpr/erase_shard/internal/gdpr/erase-shard
POST/api/v1/audit/export/v1/audit/export
GET/api/v1/tenants/v1/tenants
POST/api/v1/tenants/v1/tenants
GET/api/v1/tenants/usage/summary/v1/tenants/usage/summary
GET/api/v1/tenants/{tenant_id}/v1/tenants/{tenant_id}
DELETE/api/v1/tenants/{tenant_id}/v1/tenants/{tenant_id}
POST/api/v1/tenants/{tenant_id}/resume/v1/tenants/{tenant_id}/reactivate
POST/api/v1/tenants/{tenant_id}/suspend/v1/tenants/{tenant_id}/suspend
GET/api/v1/tenants/{tenant_id}/usage/v1/tenants/{tenant_id}/usage
GET/assertion-policies/{name}/v1/assertions/policies/{name}
PUT/assertion-policies/{name}/v1/assertions/policies/{name}
POST/assertion-relations/v1/assertions/relations
POST/assertion-relations/{id}/revoke/v1/assertions/relations/{id}/revoke
GET/assertion-resolve/v1/assertions/resolve
GET/debug/pprof/heap/admin/debug/pprof/heap
GET/debug/pprof/profile/admin/debug/pprof/profile
GET/debug/stats/v1/system/stats
POST/events/append/v1/ingest/events
POST/import/v1/ingest/import
GET/object-changes/v1/changes
GET/searches/saved/v1/search/saved
POST/searches/saved/v1/search/saved
GET/searches/saved/{id}/v1/search/saved/{id}
PUT/searches/saved/{id}/v1/search/saved/{id}
DELETE/searches/saved/{id}/v1/search/saved/{id}
POST/searches/saved/{id}/run/v1/search/saved/{id}/run

The /api/v1/tenants* and /api/v1/audit/export rows, the /admin/platform/* rows and the /internal/* rows are Enterprise-track routes.

Removed routes

MethodOld pathReplacement or reason
POST/ingest/logsduplicate of OTLP /v1/logs
POST/ingest/metricsduplicate of OTLP /v1/metrics
POST/ingest/tracesduplicate of OTLP /v1/traces
GET/types/embed-configADR-0309: no write-time embedding
POST/types/embed-configADR-0309: no write-time embedding
GET/memory/recallmerged: POST /v1/memory/recall is the one recall route
GET/graph/streamduplicate handler of /graph/changes
POST/identity/alias-blocking/runno caller
GET/modulesfolded into /v1/system/specs
GET/workflows/exportmigration-only; no production use
GET/audit/entriesmerged into /v1/audit/log
GET/log/headglobal untenanted log, no named partner (security finding)
POST/log/leafsame
GET/log/leavessame
GET/export/features/{branch}/{object_type}moves out with media epic
POST/tokensdedup tokens: no named partner; name clashes with auth tokens
GET/tokens/statsdedup tokens
GET/tokens/{id}dedup tokens
DELETE/tokens/{id}dedup tokens
GET/pipelinesgrok/dissect transforms are OpenETL work (ADR-0203)
POST/pipelinesgrok/dissect transforms are OpenETL work (ADR-0203)
GET/geo/nearbyno caller; SQL GEOFENCE/S2_DWITHIN cover it
POST/admin/backup/startduplicate of POST /admin/backup
POST/admin/phash-index/rebuildmoves out with media epic
GET/api/v1/audit/logduplicate of /audit/log
GET/api-docs/trailing-slash duplicate
GET/attestationstub; no caller
POST/embed/audioADR-0309: media embedding is OpenETL
POST/embed/batchmerged: POST /v1/embed accepts a list
POST/embed/faceADR-0309: media embedding is OpenETL
POST/embed/imageADR-0309: media embedding is OpenETL
POST/embed/videoADR-0309: media embedding is OpenETL
POST/entities/mergerewrites a store that no longer exists
GET/metrics.jsonlegacy pre-v0.6 scraper alias of /metrics
GET/statsdead; SDKs use /debug/stats
POST/v1/namespaces/{name}/branchduplicate of /schema/branches/
GET/webhooksmerged: webhooks become a channel of /v1/notification-rules
POST/webhooksmerged: webhooks become a channel of /v1/notification-rules
DELETE/webhooks/{id}merged into /v1/notification-rules

Example

TOKEN=<a registry token>   # minted on the loopback admin listener
curl -s -X POST http://127.0.0.1:9090/v1/query \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sql": "SELECT * FROM Person LIMIT 5", "purpose": "analytics"}'

/v1/query is read-only. Writes go through POST /v1/ingest, POST /v1/ingest/bulk or POST /v1/ingest/auto.

SDK changes

The Python, TypeScript and Go SDKs keep method names where the operation survives, so most callers change base URLs and not code. Exceptions:

  • Removed wrappers (route removed or Enterprise-only): list_modules (use GET /v1/system/specs); register_webhook, list_webhooks, delete_webhook (webhooks are now the webhook_url and webhook_headers channel of the notification-rule wrappers, /v1/notification-rules); cluster_topology, cluster_rebalance, cluster_drain, cluster_nodes; the transparency log client; AuditClient.entries and find_by_request_id (use AuditClient.log); the dedup-token remember, check, revoke, stats methods; list_pipelines and define_pipeline; embed_image, embed_face, embed_audio, embed_video (media embedding is OpenETL work); Namespace.branch_from (use the schema-branch wrappers on /v1/schema/branches/{name}); every tenant-administration method except me.
  • Reshaped: memory search and recall are now POST /v1/memory/recall with a JSON body (the GET form is removed). embed_batch(texts) posts {"texts": [...]} to POST /v1/embed. The token client wraps the tenant self-service routes (list_self, self_audit, rotate_self, revoke_self).
  • Added: the media-work requeue; files head, list and media_content; memory recall_stream, remember_procedure and recall_procedure; governance erase, deletion_status and verify_receipt; Python async mirrors for all of these.
Contract tests
The SDK-to-HTTP contract matrix was translated from the route map, not regenerated against a built 3.0 server. Treat the SDK method list as unverified against a 3.0 binary until it is regenerated.

Other 3.0 removals

The domain media-matching SQL operators (FACE_SEARCH, VOICE_MATCH, MATCH_PHOTODNA, MATCH_PDQ, VIDEO_FINGERPRINT_MATCH) are removed from core SQL; the parser returns a migration error naming the replacement (OpenETL-supplied vectors plus generic vector search, or SIMILAR_IMAGE). The matching SDK methods are removed too.