HTTP route restructure under /v1
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/logsand/v1/metrics, and the loopback/admin/*listener. /admin/*is served only on the loopback admin listener (default127.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:
| Method | Old path | New 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
| Method | Old path | Replacement or reason |
|---|---|---|
| POST | /ingest/logs | duplicate of OTLP /v1/logs |
| POST | /ingest/metrics | duplicate of OTLP /v1/metrics |
| POST | /ingest/traces | duplicate of OTLP /v1/traces |
| GET | /types/embed-config | ADR-0309: no write-time embedding |
| POST | /types/embed-config | ADR-0309: no write-time embedding |
| GET | /memory/recall | merged: POST /v1/memory/recall is the one recall route |
| GET | /graph/stream | duplicate handler of /graph/changes |
| POST | /identity/alias-blocking/run | no caller |
| GET | /modules | folded into /v1/system/specs |
| GET | /workflows/export | migration-only; no production use |
| GET | /audit/entries | merged into /v1/audit/log |
| GET | /log/head | global untenanted log, no named partner (security finding) |
| POST | /log/leaf | same |
| GET | /log/leaves | same |
| GET | /export/features/{branch}/{object_type} | moves out with media epic |
| POST | /tokens | dedup tokens: no named partner; name clashes with auth tokens |
| GET | /tokens/stats | dedup tokens |
| GET | /tokens/{id} | dedup tokens |
| DELETE | /tokens/{id} | dedup tokens |
| GET | /pipelines | grok/dissect transforms are OpenETL work (ADR-0203) |
| POST | /pipelines | grok/dissect transforms are OpenETL work (ADR-0203) |
| GET | /geo/nearby | no caller; SQL GEOFENCE/S2_DWITHIN cover it |
| POST | /admin/backup/start | duplicate of POST /admin/backup |
| POST | /admin/phash-index/rebuild | moves out with media epic |
| GET | /api/v1/audit/log | duplicate of /audit/log |
| GET | /api-docs/ | trailing-slash duplicate |
| GET | /attestation | stub; no caller |
| POST | /embed/audio | ADR-0309: media embedding is OpenETL |
| POST | /embed/batch | merged: POST /v1/embed accepts a list |
| POST | /embed/face | ADR-0309: media embedding is OpenETL |
| POST | /embed/image | ADR-0309: media embedding is OpenETL |
| POST | /embed/video | ADR-0309: media embedding is OpenETL |
| POST | /entities/merge | rewrites a store that no longer exists |
| GET | /metrics.json | legacy pre-v0.6 scraper alias of /metrics |
| GET | /stats | dead; SDKs use /debug/stats |
| POST | /v1/namespaces/{name}/branch | duplicate of /schema/branches/ |
| GET | /webhooks | merged: webhooks become a channel of /v1/notification-rules |
| POST | /webhooks | merged: 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(useGET /v1/system/specs);register_webhook,list_webhooks,delete_webhook(webhooks are now thewebhook_urlandwebhook_headerschannel of the notification-rule wrappers,/v1/notification-rules);cluster_topology,cluster_rebalance,cluster_drain,cluster_nodes; the transparency log client;AuditClient.entriesandfind_by_request_id(useAuditClient.log); the dedup-tokenremember,check,revoke,statsmethods;list_pipelinesanddefine_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 exceptme. - Reshaped: memory
searchandrecallare nowPOST /v1/memory/recallwith a JSON body (theGETform is removed).embed_batch(texts)posts{"texts": [...]}toPOST /v1/embed. The token client wraps the tenant self-service routes (list_self,self_audit,rotate_self,revoke_self). - Added: the media-work
requeue; fileshead,listandmedia_content; memoryrecall_stream,remember_procedureandrecall_procedure; governanceerase,deletion_statusandverify_receipt; Python async mirrors for all of these.
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.