{ "components": { "parameters": { "DbKey": { "description": "API key of the x-oc-db-user user.", "in": "header", "name": "x-oc-db-key", "required": false, "schema": { "type": "string" } }, "DbUser": { "description": "Acting database user (role, grant and row-policy checks). Send with x-oc-db-key.", "in": "header", "name": "x-oc-db-user", "required": false, "schema": { "type": "string" } } }, "responses": { "Error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error. The body always carries `error`; 429 and 503 may carry a Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "schemas": { "Error": { "additionalProperties": true, "properties": { "class": { "description": "Machine-readable error class, when the engine sets one.", "type": "string" }, "error": { "description": "A message string, or (vector-index record routes) a structured error object.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ErrorDetail" } ] } }, "required": [ "error" ], "type": "object" }, "ErrorDetail": { "additionalProperties": true, "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "details": { "description": "Error-specific context.", "type": "object" }, "message": { "description": "Human-readable message.", "type": "string" }, "retryable": { "description": "Whether retrying the same request can succeed.", "type": "boolean" }, "status": { "description": "The HTTP status, repeated.", "type": "integer" } }, "required": [ "code", "message" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "The database's API token.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "The OriginChainDB database HTTP API. Generated from the engine's routes; do not edit by hand.", "title": "OriginChainDB HTTP API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/health": { "get": { "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always {\"status\":\"ok\",\"tenants\":null,\"schemas\":null}.", "properties": { "schemas": { "const": null }, "status": { "type": "string" }, "tenants": { "const": null } }, "required": [ "status", "tenants", "schemas" ], "type": "object" } } }, "description": "OK" } }, "security": [], "summary": "Reports that the engine process is alive, with a constant JSON body.", "tags": [ "system" ] } }, "/ready": { "get": { "operationId": "ready", "parameters": [ { "in": "query", "name": "require", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "status is ready, degraded or not-ready. The same body is also returned with 503: on a bare call when storage is unhealthy, or with ?require=write|read when that dimension is not ready. An unknown ?require value answers 400.", "properties": { "pressure": { "items": { "type": "string" }, "type": "array" }, "quorum_contact_loss_ms": { "type": "integer" }, "read_ready": { "type": "boolean" }, "rss_mib": { "type": "integer" }, "status": { "type": "string" }, "storage": { "description": "state is ok, busy or broken; last_ok_ms_ago appears when busy, reason when broken.", "properties": { "last_ok_ms_ago": { "type": "integer" }, "reason": { "type": "string" }, "state": { "type": "string" } }, "required": [ "state" ], "type": "object" }, "write_ready": { "type": "boolean" } }, "required": [ "status", "write_ready", "read_ready", "rss_mib", "pressure", "storage" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Reports whether the engine can serve traffic, including write and read readiness and any pressure conditions.", "tags": [ "system" ] } }, "/v1/capabilities": { "get": { "operationId": "capabilities", "responses": { "200": { "content": { "application/json": { "schema": { "description": "Each family is an object, typically with supported and roadmap lists (roadmap entries are {variant, eta}); some families add preview, caveats, notes, limits or availability flags. The kernel family is host-dependent.", "properties": { "engine_version": { "type": "string" }, "es_aggregations": { "type": "object" }, "fts_lemmatizers": { "type": "object" }, "fts_tokenizer_kinds": { "type": "object" }, "geo_index_kinds": { "type": "object" }, "graph_embedding_aggregators": { "type": "object" }, "graph_embedding_algos": { "type": "object" }, "index_kinds": { "type": "object" }, "index_residency": { "type": "object" }, "kernel": { "type": "object" }, "mssql_tds_dialect": { "type": "object" }, "mysql_wire_dialect": { "type": "object" }, "postgres_wire": { "type": "object" }, "quantization": { "type": "object" }, "replication_modes": { "type": "object" }, "row_optimistic_concurrency": { "type": "object" }, "search_execution_limits": { "type": "object" }, "sql_constraint_kinds": { "type": "object" }, "sql_cte": { "type": "object" }, "sql_insert_on_conflict": { "type": "object" }, "sql_isolation_levels": { "type": "object" }, "sql_joins": { "type": "object" }, "sql_materialized_view_refresh_modes": { "type": "object" }, "sql_oracle_compat": { "type": "object" }, "sql_procedure_languages": { "type": "object" }, "sql_statement_complexity": { "type": "object" }, "sql_trigger_kinds": { "type": "object" }, "sql_udf_languages": { "type": "object" }, "sql_window_functions": { "type": "object" }, "topology": { "type": "object" } }, "required": [ "engine_version", "quantization", "index_kinds", "index_residency", "topology", "kernel", "geo_index_kinds", "fts_tokenizer_kinds", "fts_lemmatizers", "search_execution_limits", "es_aggregations", "replication_modes", "graph_embedding_algos", "graph_embedding_aggregators", "sql_isolation_levels", "sql_constraint_kinds", "sql_insert_on_conflict", "sql_window_functions", "sql_materialized_view_refresh_modes", "row_optimistic_concurrency", "sql_trigger_kinds", "sql_procedure_languages", "sql_udf_languages", "mssql_tds_dialect", "mysql_wire_dialect", "postgres_wire", "sql_joins", "sql_cte", "sql_oracle_compat", "sql_statement_complexity" ], "type": "object" } } }, "description": "OK" } }, "security": [], "summary": "Returns the live support matrix of features, index kinds, SQL constructs and wire protocols this engine serves.", "tags": [ "system" ] } }, "/v1/tenants/{tenant}/audit": { "get": { "operationId": "audit_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "limit defaults to 100 and is capped at 1000. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "entries": { "items": { "description": "action is a dotted verb such as user.create, grant.put, rls.delete; detail is structured metadata (never row data); prev_hash is an empty string for the first entry.", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "at_unix": { "type": "integer" }, "detail": {}, "hash": { "type": "string" }, "prev_hash": { "type": "string" }, "seq": { "type": "integer" }, "target": { "type": "string" } }, "required": [ "seq", "at_unix", "actor", "action", "target", "detail", "prev_hash", "hash" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the most recent entries of the tenant's tamper-evident audit log, newest first.", "tags": [ "audit" ] } }, "/v1/tenants/{tenant}/audit/export": { "get": { "operationId": "audit_export", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/x-ndjson": { "schema": { "description": "Not a single JSON document: the body is one JSON object per line (the fields shown), ascending by seq, joined by newlines with no trailing newline; empty body when the log is empty. Each line carries its hash links so the chain can be re-verified offline. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "at_unix": { "type": "integer" }, "detail": {}, "hash": { "type": "string" }, "prev_hash": { "type": "string" }, "seq": { "type": "integer" }, "target": { "type": "string" } }, "required": [ "seq", "at_unix", "actor", "action", "target", "detail", "prev_hash", "hash" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Exports the tenant's complete audit log as newline-delimited JSON, oldest first, for ingestion into a security monitoring system.", "tags": [ "audit" ] } }, "/v1/tenants/{tenant}/audit/verify": { "get": { "operationId": "audit_verify", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "first_broken_seq is always present and null when the chain is intact. A broken chain is reported with ok=false and a 200, not an error status. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "detail": { "type": "string" }, "entries": { "type": "integer" }, "first_broken_seq": { "type": "integer" }, "ok": { "type": "boolean" } }, "required": [ "ok", "entries", "first_broken_seq", "detail" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Verifies the integrity of the tenant's hash-chained audit log and reports the first entry that fails, if any.", "tags": [ "audit" ] } }, "/v1/tenants/{tenant}/cypher": { "post": { "operationId": "cypher_exec", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "default_schema (namespace.table) is used for node patterns without a label. params supplies $name values as scalars (string, number, bool or null). explain=true (default false) returns the plan a read would run without executing it, and is refused with 400 for a query that writes.", "properties": { "cypher": { "type": "string" }, "default_schema": { "type": "string" }, "explain": { "type": "boolean" }, "params": { "type": "object" } }, "required": [ "cypher" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "kind is select (rows), insert or merge (rows_inserted), update (rows_affected), delete (rows_deleted) or explain (plan); only the fields for that kind are present. Constraint violations on writes answer 409.", "properties": { "kind": { "type": "string" }, "plan": { "type": "string" }, "rows": { "items": { "type": "object" }, "type": "array" }, "rows_affected": { "type": "integer" }, "rows_deleted": { "type": "integer" }, "rows_inserted": { "type": "integer" } }, "required": [ "kind" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs an openCypher query, read or write, and returns its rows or write counts.", "tags": [ "cypher" ] } }, "/v1/tenants/{tenant}/db/grants": { "delete": { "operationId": "revoke_grant", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Sent as a JSON body on DELETE (not a query string). Removes the whole grant row; there is no partial-privilege revoke. Succeeds even when no such grant exists.", "properties": { "object": { "type": "string" }, "role": { "type": "string" } }, "required": [ "role", "object" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always {\"revoked\": true} on success. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Revokes a role's grant on an object, removing every privilege and column mask it carried.", "tags": [ "db" ] }, "get": { "operationId": "list_grants", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "grants": { "items": { "description": "privileges is a five-character SIUDR rendering (SELECT, INSERT, UPDATE, DELETE, REFERENCES) with an underscore for a privilege not held, e.g. S____.", "properties": { "masked_columns": { "items": { "type": "string" }, "type": "array" }, "object": { "type": "string" }, "privileges": { "type": "string" }, "role": { "type": "string" } }, "required": [ "role", "object", "privileges", "masked_columns" ], "type": "object" }, "type": "array" } }, "required": [ "grants" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists every privilege grant in the tenant with the privileges and masked columns each role holds on each object.", "tags": [ "db" ] }, "post": { "operationId": "put_grant", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "privileges is TEXT, not a list: SQL words ALL, SELECT, INSERT, UPDATE, DELETE, REFERENCES, NONE and/or letter sets from S,I,U,D,R (e.g. SIUDR, SI, \"SELECT, INSERT\"), separated by commas, spaces, + or |. An unrecognised token is a 400. object is a table id namespace.table or *.", "properties": { "masked_columns": { "items": { "type": "string" }, "type": "array" }, "object": { "type": "string" }, "privileges": { "type": "string" }, "role": { "type": "string" } }, "required": [ "role", "object", "privileges" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "warnings is omitted when empty; it is present when the object is not a registered table (the grant is stored but applies to nothing until that table exists) or could not be verified. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "granted": { "type": "boolean" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "granted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Grants a role privileges on a table, or on every table with the object *, optionally masking columns, and replaces any existing grant for that role and object.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/matrix": { "get": { "operationId": "matrix", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "objects", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The objects query parameter is a comma-separated list of table ids; omitted or empty means every registered table. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "objects": { "items": { "description": "roles is a map keyed by role name; each value is {priv: SIUDR string, masked: [column names]}. Objects are sorted by id.", "properties": { "object": { "type": "string" }, "roles": { "description": "Value shape for each role-name key.", "properties": { "masked": { "items": { "type": "string" }, "type": "array" }, "priv": { "type": "string" } }, "required": [ "priv", "masked" ], "type": "object" } }, "required": [ "object", "roles" ], "type": "object" }, "type": "array" } }, "required": [ "objects" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the effective privilege matrix: for each table, the privileges and masked columns every role resolves to, including inherited roles.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/rls": { "delete": { "operationId": "delete_rls", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "role", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always {\"deleted\": true} on success, including when no such policy existed. The policy is identified by query string (unlike revoking a grant, which takes a JSON body). Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes the row-level security policy for a role on a table.", "tags": [ "db" ] }, "get": { "operationId": "list_rls", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "using is the stored USING predicate text; command is lower-case (e.g. select, all). Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "policies": { "items": { "properties": { "command": { "type": "string" }, "role": { "type": "string" }, "table": { "type": "string" }, "using": { "type": "string" } }, "required": [ "table", "role", "using", "command" ], "type": "object" }, "type": "array" } }, "required": [ "policies" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists every row-level security policy in the tenant.", "tags": [ "db" ] }, "post": { "operationId": "put_rls", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "using is a predicate such as \"owner = CURRENT_USER AND region IN ('us','eu')\" and is validated at create time (invalid = 400). command defaults to select and is stored lower-cased; it is not validated, and only select and all policies are applied to reads. One policy per (table, role); a new one replaces the old.", "properties": { "command": { "type": "string" }, "role": { "type": "string" }, "table": { "type": "string" }, "using": { "type": "string" } }, "required": [ "table", "role", "using" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "warnings is omitted when empty; it is present when the table is not registered (the policy then applies to nothing) or could not be verified. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "ok": { "type": "boolean" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "ok" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates or replaces the row-level security policy that limits which rows of a table a role can read.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/rls/effective": { "get": { "operationId": "rls_effective", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "user", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "restricted is true when at least one applicable policy filters this user's reads; applies and is_superuser are resolved through role inheritance. policies lists every policy on the table. 404 when the user does not exist. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "is_superuser": { "type": "boolean" }, "policies": { "items": { "properties": { "applies": { "type": "boolean" }, "command": { "type": "string" }, "role": { "type": "string" }, "using": { "type": "string" } }, "required": [ "role", "using", "command", "applies" ], "type": "object" }, "type": "array" }, "restricted": { "type": "boolean" }, "table": { "type": "string" }, "user": { "type": "string" } }, "required": [ "user", "table", "restricted", "is_superuser", "policies" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Shows which row-level security policies apply to a given database user on a table, without running a query as that user.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/roles": { "get": { "operationId": "list_roles", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "roles": { "items": { "description": "system is true for the built-in roles ll_admin and ll_system, which are always listed (created_unix 0 when not yet stored).", "properties": { "created_unix": { "type": "integer" }, "inherits": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "system": { "type": "boolean" } }, "required": [ "name", "system", "inherits", "created_unix" ], "type": "object" }, "type": "array" } }, "required": [ "roles" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the tenant's database roles, including the built-in system roles.", "tags": [ "db" ] }, "post": { "operationId": "create_role", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "name must be non-empty, free of control characters, and not a reserved system role name (ll_admin, ll_system). Every role named in inherits must already exist, else 400.", "properties": { "inherits": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Echoes the trimmed role name. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates a database role, optionally inheriting the privileges of existing roles.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/roles/{name}": { "delete": { "operationId": "delete_role", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "cascade", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "cascade defaults to false. Without it, a role that is still referenced is refused with 409 and a body {error: role_has_dependents, role, dependents: {grants, rls_policies, members, inherited_by}}. System roles cannot be deleted (400). Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "cascaded": { "description": "grants = objects the role held grants on; rls_policies = tables with a policy for the role; members = usernames holding the role; inherited_by = roles inheriting it. All empty when nothing referenced the role.", "properties": { "grants": { "items": { "type": "string" }, "type": "array" }, "inherited_by": { "items": { "type": "string" }, "type": "array" }, "members": { "items": { "type": "string" }, "type": "array" }, "rls_policies": { "items": { "type": "string" }, "type": "array" } }, "required": [ "grants", "rls_policies", "members", "inherited_by" ], "type": "object" }, "deleted": { "type": "boolean" } }, "required": [ "deleted", "cascaded" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes a database role, refusing while grants, policies, members or inheriting roles still reference it unless cascade=true is passed.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/users": { "get": { "operationId": "list_users", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "users": { "items": { "description": "auth is one of: password, api_key. Key material is never returned here, only the count of keys.", "properties": { "api_key_count": { "type": "integer" }, "auth": { "type": "string" }, "created_unix": { "type": "integer" }, "disabled": { "type": "boolean" }, "roles": { "items": { "type": "string" }, "type": "array" }, "username": { "type": "string" } }, "required": [ "username", "auth", "roles", "api_key_count", "disabled", "created_unix" ], "type": "object" }, "type": "array" } }, "required": [ "users" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the tenant's database users with their authentication method, roles and number of API keys.", "tags": [ "db" ] }, "post": { "operationId": "create_user", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "auth is one of: password, api_key. password is required (non-empty) when auth is password and must use the portable character set accepted by every wire protocol. roles defaults to []. An existing username is a 400.", "properties": { "auth": { "type": "string" }, "password": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "username": { "type": "string" } }, "required": [ "username", "auth" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "api_key is always present: for api_key users it is the plaintext key, returned only this once and never retrievable again; for password users it is null. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "api_key": { "type": "string" }, "username": { "type": "string" } }, "required": [ "username", "api_key" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates a database user that authenticates with either a password or a generated API key.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/users/{username}": { "delete": { "operationId": "delete_user", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "username", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always {\"deleted\": true} on success, including when the user did not exist. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes a database user and all of its credentials.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/db/users/{username}/api-key": { "post": { "operationId": "rotate_user_key", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "username", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "api_key is the new plaintext key, returned only this once and never retrievable again. The endpoint reads no body; a non-empty body may be rejected with 400. 404 when the user does not exist. Requires the tenant bearer; a request that also presents a database-user identity must act as a database superuser.", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Issues an additional API key for a database user; keys issued earlier remain valid.", "tags": [ "db" ] } }, "/v1/tenants/{tenant}/diagnostics": { "post": { "operationId": "report_client_diagnostics", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "1 to 32 events per request. A request with one invalid event is refused whole (422 invalid_diagnostics) and relays nothing. Diagnostics are off by default in every SDK.", "properties": { "events": { "items": { "description": "One call the SDK observed against this database. Unknown fields are refused. client: typescript | python | go | cli. method: GET | POST | PUT | PATCH | DELETE. path: the /v1/tenants/... path called (at most 512 characters); only its route template is kept. outcome: success | error | cancelled | timeout | denied. duration_ms: 0 to 3600000. http_status: 100 to 599. error_category (failed outcomes only): validation | auth | permission | not_found | conflict | rate_limited | capacity | timeout | cancelled | unavailable | network | internal | unknown. error_code (failed outcomes only): a SQLSTATE or a short machine code. logical_request_id: a UUID shared by every attempt of one logical call; attempt: 1 to 100. transport: not_sent | no_response, for a failure that has no http_status. No free text, SQL or stack traces are accepted.", "properties": { "attempt": { "type": "integer" }, "client": { "type": "string" }, "client_version": { "type": "string" }, "duration_ms": { "type": "number" }, "error_category": { "type": "string" }, "error_code": { "type": "string" }, "http_status": { "type": "integer" }, "logical_request_id": { "type": "string" }, "method": { "type": "string" }, "outcome": { "type": "string" }, "path": { "type": "string" }, "request_id": { "type": "string" }, "transport": { "type": "string" } }, "required": [ "client", "client_version", "method", "path", "outcome", "duration_ms", "logical_request_id" ], "type": "object" }, "type": "array" } }, "required": [ "events" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "description": "202. accepted = events relayed; dropped = events over this engine's limit (600 per minute), dropped and never queued. telemetry is \"off\" (and every event is dropped) when this engine's telemetry is disabled.", "properties": { "accepted": { "type": "integer" }, "dropped": { "type": "integer" }, "telemetry": { "type": "string" } }, "required": [ "accepted", "dropped" ], "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reports the SDK's own opt-in diagnostics for its calls to this database; the engine relays them into its telemetry.", "tags": [ "diagnostics" ] } }, "/v1/tenants/{tenant}/fts": { "get": { "operationId": "fts_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Sorted by (table, field). complete is always true on a 200; an incomplete cluster-wide listing answers 502 instead. Entries the caller may not read are omitted.", "properties": { "complete": { "type": "boolean" }, "fields": { "items": { "properties": { "avg_doc_length": { "type": "number" }, "field": { "type": "string" }, "num_docs": { "type": "integer" }, "table": { "type": "string" } }, "required": [ "table", "field", "num_docs", "avg_doc_length" ], "type": "object" }, "type": "array" } }, "required": [ "fields", "complete" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists every full-text indexed field in the tenant with its document count and average document length.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/_aggs": { "post": { "operationId": "fts_aggs", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "field names the full-text field whose per-document values (written via the doc endpoint) are aggregated. aggs must be non-empty (400 otherwise). filter_expr is accepted only to be refused: any non-null value, top-level or inside search, answers 501.", "properties": { "aggs": { "description": "Map of aggregation name -> aggregation node. A node is {\"\": {...}, \"aggs\": {}}. Bucket kinds: terms, range, histogram, date_histogram, filter, filters, missing, global. Metric kinds: count, min, max, sum, avg, stats, extended_stats, cardinality, percentiles, percentile_ranks, top_hits. Pipeline kinds: bucket_sort, cumulative_sum, derivative, serial_diff, moving_fn, bucket_script, bucket_selector, avg_bucket, sum_bucket, min_bucket, max_bucket, stats_bucket. Fields are named with \"field\".", "type": "object" }, "field": { "type": "string" }, "search": { "description": "A _search request body selecting the documents to aggregate (doc_values_field is refused here). Absent means match_all over field.", "properties": { "default_field": { "type": "string" }, "exact_total": { "type": "boolean" }, "min_score": { "type": "number" }, "params": { "description": "BM25 tunables; both optional.", "properties": { "b": { "type": "number" }, "k1": { "type": "number" } }, "type": "object" }, "query": {}, "search_after": { "description": "values holds one JSON scalar per sort key (any scalar type; null means missing) and must match the sort length. doc_id is the tiebreak of the last hit seen.", "properties": { "doc_id": { "type": "string" }, "values": { "items": {}, "type": "array" } }, "required": [ "values" ], "type": "object" }, "sort": { "items": { "description": "role: keyword|numeric|date|boolean|score|doc_id (score and doc_id ignore field). missing: \"last\" (default) | \"first\" | {\"value\": \"\"}. mode: min|max|sum|avg|median (multi-value reduction).", "properties": { "ascending": { "type": "boolean" }, "field": { "type": "string" }, "missing": {}, "mode": { "type": "string" }, "role": { "type": "string" }, "truncate": { "type": "boolean" } }, "required": [ "field", "ascending", "role" ], "type": "object" }, "type": "array" }, "table": { "type": "string" }, "top_k": { "type": "integer" }, "total_ceiling": { "type": "integer" }, "unindexed_fields_are_empty": { "type": "boolean" }, "universe_field": { "type": "string" } }, "required": [ "query" ], "type": "object" } }, "required": [ "field" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "doc_count is the number of documents the tree was evaluated over (the whole match set, never a ranked prefix).", "properties": { "aggs": { "description": "Map of aggregation name -> result object. Each result is internally tagged with \"kind\": buckets | single_bucket | value | stats | extended_stats | cardinality | percentiles | percentile_ranks | top_hits. Bucket results carry \"buckets\" (each with key, doc_count and nested \"aggs\"); value results carry \"value\".", "type": "object" }, "doc_count": { "type": "integer" } }, "required": [ "doc_count", "aggs" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs an aggregation tree over the documents a full-text query matches, or over every document indexed under the field.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/_search": { "post": { "operationId": "fts_dsl_search", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "table is optional and must equal the URL table if sent. top_k defaults to 10 and may not exceed the server hit ceiling (default 10,000). search_after requires a non-empty sort. doc_values_field names the field whose stored facet values back numeric_range / function_score clauses and sorts. A non-null filter_expr key answers 501. Unknown top-level keys are ignored (body is not strictly checked).", "properties": { "default_field": { "type": "string" }, "doc_values_field": { "type": "string" }, "exact_total": { "type": "boolean" }, "min_score": { "type": "number" }, "params": { "description": "BM25 tunables; both optional.", "properties": { "b": { "type": "number" }, "k1": { "type": "number" } }, "type": "object" }, "query": {}, "search_after": { "description": "values holds one JSON scalar per sort key (any scalar type; null means missing) and must match the sort length. doc_id is the tiebreak of the last hit seen.", "properties": { "doc_id": { "type": "string" }, "values": { "items": {}, "type": "array" } }, "required": [ "values" ], "type": "object" }, "sort": { "items": { "description": "role: keyword|numeric|date|boolean|score|doc_id (score and doc_id ignore field). missing: \"last\" (default) | \"first\" | {\"value\": \"\"}. mode: min|max|sum|avg|median (multi-value reduction).", "properties": { "ascending": { "type": "boolean" }, "field": { "type": "string" }, "missing": {}, "mode": { "type": "string" }, "role": { "type": "string" }, "truncate": { "type": "boolean" } }, "required": [ "field", "ascending", "role" ], "type": "object" }, "type": "array" }, "table": { "type": "string" }, "top_k": { "type": "integer" }, "total_ceiling": { "type": "integer" }, "unindexed_fields_are_empty": { "type": "boolean" }, "universe_field": { "type": "string" } }, "required": [ "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "total counts matches before top_k truncation; total_is_lower_bound appears (true) only when total is a lower bound.", "properties": { "hits": { "items": { "properties": { "doc_id": { "type": "string" }, "score": { "type": "number" } }, "required": [ "doc_id", "score" ], "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "total_is_lower_bound": { "type": "boolean" } }, "required": [ "total", "hits" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs a structured full-text query against a table's index and returns ranked document ids with the total match count.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/_suggest": { "post": { "operationId": "fts_suggest", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Tagged by kind: completion | term | phrase. completion requires prefix and accepts size, order (frequency | lexicographic), max_scan. term requires text and accepts size, max_edits, mode (missing | popular | always), min_word_length. phrase requires text and accepts size, max_edits, candidates_per_term, confidence (default 1.0), min_word_length. A missing or unknown kind is rejected by body parsing.", "properties": { "candidates_per_term": { "type": "integer" }, "confidence": { "type": "number" }, "field": { "type": "string" }, "kind": { "type": "string" }, "max_edits": { "type": "integer" }, "max_scan": { "type": "integer" }, "min_word_length": { "type": "integer" }, "mode": { "type": "string" }, "order": { "type": "string" }, "prefix": { "type": "string" }, "size": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "kind", "field" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Tagged by kind, echoing the request. source: segmented | legacy_dictionary. completion carries prefix, completions, frequency_ranked, df_exact, scanned. term carries entries, frequency_ranked, df_exact. phrase carries input, input_score, options, cooccurrence_available, df_exact, cooccurrence_probes.", "properties": { "completions": { "items": { "properties": { "df": { "type": "integer" }, "score": { "type": "number" }, "text": { "type": "string" }, "total_tf": { "type": "integer" } }, "required": [ "text", "df", "total_tf", "score" ], "type": "object" }, "type": "array" }, "cooccurrence_available": { "type": "boolean" }, "cooccurrence_probes": { "type": "integer" }, "df_exact": { "type": "boolean" }, "entries": { "items": { "properties": { "candidates_truncated": { "type": "boolean" }, "df": { "type": "integer" }, "options": { "items": { "properties": { "df": { "type": "integer" }, "distance": { "type": "integer" }, "score": { "type": "number" }, "text": { "type": "string" } }, "required": [ "text", "distance", "df", "score" ], "type": "object" }, "type": "array" }, "text": { "type": "string" } }, "required": [ "text", "df", "options", "candidates_truncated" ], "type": "object" }, "type": "array" }, "frequency_ranked": { "type": "boolean" }, "input": { "items": { "type": "string" }, "type": "array" }, "input_score": { "type": "number" }, "kind": { "type": "string" }, "options": { "items": { "properties": { "cooccurrence_score": { "type": "number" }, "corrected_terms": { "type": "integer" }, "score": { "type": "number" }, "term_score": { "type": "number" }, "terms": { "items": { "type": "string" }, "type": "array" }, "text": { "type": "string" } }, "required": [ "text", "terms", "score", "term_score", "cooccurrence_score", "corrected_terms" ], "type": "object" }, "type": "array" }, "prefix": { "type": "string" }, "scanned": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "kind", "source", "df_exact" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns completion, spelling-correction or phrase-correction suggestions from a full-text field's term dictionary.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}": { "get": { "operationId": "fts_search", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "mode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "k", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "fuzzy", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "highlight", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "facets", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "explain", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shape depends on mode. Default (mode=boolean) and mode=phrase: an array of matching doc ids. mode=bm25: an array of {doc_id, score} (k defaults to 10). mode=bm25 with highlight=true or facets=: an object {hits: [{doc_id, score, highlights?}], facets?: {field: [buckets]}}. mode=bm25 with explain=true: a scoring-explanation object. `filter_expr` is accepted but answered 501." } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Searches the full-text index of a table field by boolean match, phrase or BM25 relevance ranking.", "tags": [ "fts" ] }, "post": { "operationId": "fts_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The document key is `doc_id`. `analyzer` is a string (\"keyword\", \"whitespace\") or an object such as {\"language\": \"english\"}; absent uses the default analyzer. `values` indexes each string as one exact token instead of analysing `text` (`text` is still required). Success is 201 with an empty body.", "properties": { "analyzer": {}, "doc_id": { "type": "string" }, "text": { "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "doc_id", "text" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Indexes the text of one document for full-text search on a table field.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}/delete": { "post": { "operationId": "fts_delete_doc", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Idempotent: deleting a document that was never indexed also succeeds.", "properties": { "doc_id": { "type": "string" } }, "required": [ "doc_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "deleted=false means nothing was stored for the document under this field and nothing was written. A caller with a row-level-security policy on the table gets the same answer for a document whose row the policy hides or that names no row.", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Removes a document from a table field's full-text index, including its stored text and facet values.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}/doc": { "post": { "operationId": "fts_set_doc", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "facets maps facet field name -> array of string values, e.g. {\"color\": [\"red\"], \"tags\": [\"a\", \"b\"]}. The text is stored for highlighting only; it does not index postings.", "properties": { "doc_id": { "type": "string" }, "facets": { "type": "object" }, "text": { "type": "string" } }, "required": [ "doc_id", "text" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Stores a document's original text and optional facet values on a full-text field for highlighting and faceting.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}/json": { "post": { "operationId": "fts_index_json", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "`paths` are dotted paths into `json`; empty or absent indexes every string leaf. Success is 201 with an empty body.", "properties": { "doc_id": { "type": "string" }, "json": {}, "paths": { "items": { "type": "string" }, "type": "array" } }, "required": [ "doc_id", "json" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Indexes the string content of a JSON document for full-text search on a table field, optionally limited to the given paths.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}/stopwords": { "post": { "operationId": "fts_install_stopwords", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The complete list for this table field; an empty array disables stopwords for the field.", "properties": { "stopwords": { "items": { "type": "string" }, "type": "array" } }, "required": [ "stopwords" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replaces the stopword list for a table field's full-text index.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/fts/{table}/{field}/synonyms": { "post": { "operationId": "fts_install_synonyms", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Maps each canonical term to an array of synonym strings; replaces any previous map for the table field in full.", "properties": { "synonyms": { "type": "object" } }, "required": [ "synonyms" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replaces the synonym map for a table field's full-text index.", "tags": [ "fts" ] } }, "/v1/tenants/{tenant}/geo/{schema}": { "get": { "operationId": "geo_config_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "fields is empty when the schema declares no geospatial index. consistent is false when stored points and the index disagree; index_repair_pending is true when a write is known to have missed the index. Either is repaired by the reindex endpoint.", "properties": { "fields": { "items": { "properties": { "consistent": { "type": "boolean" }, "field": { "type": "string" }, "index": { "type": "string" }, "index_repair_pending": { "type": "boolean" }, "indexed": { "type": "integer" }, "points": { "type": "integer" }, "source": { "type": "string" } }, "required": [ "field", "source", "index", "points", "indexed", "consistent", "index_repair_pending" ], "type": "object" }, "type": "array" }, "schema": { "type": "string" } }, "required": [ "schema", "fields" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns a schema's declared geospatial indexes with live point and index counts per field.", "tags": [ "geo" ] } }, "/v1/tenants/{tenant}/geo/{schema}/{field}": { "get": { "operationId": "geo_search", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "field", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "mode", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "lat", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "lon", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "radius_m", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "k", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "min_lat", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "min_lon", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "max_lat", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "max_lon", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "mode is bbox (default), radius or nearest. bbox needs min_lat, min_lon, max_lat and max_lon (min_lon > max_lon crosses the antimeridian); radius needs lat, lon and radius_m (metres); nearest needs lat and lon and takes k (default 10). limit caps hits after ranking. doc_id is the row's primary key; distance_m is in metres and omitted in bbox mode. 404 when the field has no declared geospatial index. index_repair_pending=true means the answer may under-report.", "properties": { "count": { "type": "integer" }, "hits": { "items": { "properties": { "distance_m": { "type": "number" }, "doc_id": { "type": "string" } }, "required": [ "doc_id" ], "type": "object" }, "type": "array" }, "index_repair_pending": { "type": "boolean" }, "mode": { "type": "string" } }, "required": [ "mode", "count", "hits", "index_repair_pending" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Searches a geospatial field by bounding box, radius or nearest neighbours.", "tags": [ "geo" ] } }, "/v1/tenants/{tenant}/graph/{schema}/all_simple_paths": { "get": { "operationId": "graph_all_simple_paths", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "src", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "dst", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_depth", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "max_paths", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Each path is its node primary keys in order. max_depth defaults to 3, max_paths to 256.", "items": { "properties": { "pks": { "items": { "type": "string" }, "type": "array" } }, "required": [ "pks" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the simple paths from one node to another along a relation, up to a depth and path-count limit.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/all_simple_paths_bidir": { "get": { "operationId": "graph_all_simple_paths_bidir", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "src", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "dst", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_depth", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "max_paths", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Requires a bidirectional relation. max_depth defaults to 3, max_paths to 256.", "items": { "properties": { "pks": { "items": { "type": "string" }, "type": "array" } }, "required": [ "pks" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the simple paths between two nodes when each hop may follow a relation edge in either direction.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/betweenness": { "get": { "operationId": "graph_betweenness", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_nodes", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "samples", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "seed", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "pk is the node's primary-key values as an array. estimated and pivots appear only when the score was sampled.", "items": { "properties": { "betweenness": { "type": "number" }, "estimated": { "type": "boolean" }, "pivots": { "type": "integer" }, "pk": { "items": {}, "type": "array" } }, "required": [ "betweenness", "pk" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Scores every node of a graph schema by betweenness centrality, exactly or by sampling.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/bfs": { "get": { "operationId": "graph_bfs", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pk", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_depth", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "max_depth defaults to 3.", "items": { "properties": { "depth": { "type": "integer" }, "pk": { "type": "string" } }, "required": [ "depth", "pk" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Walks a relation breadth-first from a node and returns each node reached with its depth.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/components": { "get": { "operationId": "graph_components", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include_rows", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One entry per node. By default each is {pk, _component} where pk is the node's primary-key values; include_rows=true (default false) returns each full row plus _component instead, with no pk key. _component is the JSON-encoded primary key of the component root. The relation must target the same schema.", "items": { "properties": { "_component": { "type": "string" }, "pk": { "items": {}, "type": "array" } }, "required": [ "_component" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Labels every node in a graph schema with its connected component, treating a self-relation as undirected.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/dangling": { "get": { "operationId": "graph_dangling", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "budget", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Read-only. budget defaults to 10,000 work units (clamped 1..100,000) and limit to 100 reports (clamped 1..1,000); the effective values are echoed. edge_model is edge_table or derived; side is src, dst or target. truncated_by (budget, limit or bytes) and next_after are null when the walk completed; pass next_after back as after to resume. Refused with 501 when a referenced table is served by another node.", "properties": { "budget": { "type": "integer" }, "dangling": { "items": { "properties": { "edge_pk": { "items": {}, "type": "array" }, "first_reference": { "type": "integer" }, "missing": { "items": { "properties": { "column": { "type": "string" }, "side": { "type": "string" }, "target": { "type": "string" }, "value": {} }, "required": [ "side", "column", "target", "value" ], "type": "object" }, "type": "array" }, "missing_total": { "type": "integer" }, "row_complete": { "type": "boolean" } }, "required": [ "edge_pk", "missing", "missing_total", "first_reference", "row_complete" ], "type": "object" }, "type": "array" }, "edge_model": { "type": "string" }, "endpoints": { "items": { "properties": { "column": { "type": "string" }, "side": { "type": "string" }, "target": { "type": "string" }, "target_registered": { "type": "boolean" } }, "required": [ "side", "column", "target", "target_registered" ], "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "next_after": { "type": "string" }, "probes": { "type": "integer" }, "relation": { "type": "string" }, "scanned_rows": { "type": "integer" }, "schema": { "type": "string" }, "truncated": { "type": "boolean" }, "truncated_by": { "type": "string" } }, "required": [ "schema", "relation", "edge_model", "endpoints", "budget", "limit", "scanned_rows", "probes", "dangling", "truncated", "truncated_by", "next_after" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reports edges whose endpoint rows no longer exist for a relation, in bounded, resumable pages.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/dijkstra": { "get": { "operationId": "graph_dijkstra", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "src", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "dst", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "weights_json", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "cost is null when dst is unreachable. weights_json is a JSON object mapping \"from|to\" primary-key pairs to non-negative weights; pairs without a weight are treated as missing edges.", "properties": { "cost": { "type": "number" } }, "required": [ "cost" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the lowest total weight of a path between two nodes, using caller-supplied edge weights.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/eigenvector_centrality": { "get": { "operationId": "graph_eigenvector_centrality", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_iter", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "tol", "required": false, "schema": { "type": "number" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "pk is the node's primary-key values as an array. max_iter defaults to 50, tol to 1e-6.", "items": { "properties": { "eigenvector": { "type": "number" }, "pk": { "items": {}, "type": "array" } }, "required": [ "eigenvector", "pk" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Scores every node of a graph schema by eigenvector centrality.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/graphsage": { "post": { "operationId": "graph_graphsage", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "feature_col names the per-row numeric-array feature column. Defaults: feature_dim 128, embedding_dim 128, hidden_dim 128 (each 1..1024), num_layers 2 (1..4), neighbor_sample_size 25 (1..50), aggregator mean (mean | max_pool | lstm), walks_per_node 10, walk_length 80, window_size 5, negative_samples 5, epochs 5, initial_lr 0.025, min_lr 0.0001, seed 0. persist defaults to false; persist=true also requires the schema DDL privilege. Graphs above 100,000 nodes are refused.", "properties": { "aggregator": { "type": "string" }, "embedding_dim": { "type": "integer" }, "epochs": { "type": "integer" }, "feature_col": { "type": "string" }, "feature_dim": { "type": "integer" }, "hidden_dim": { "type": "integer" }, "initial_lr": { "type": "number" }, "min_lr": { "type": "number" }, "negative_samples": { "type": "integer" }, "neighbor_sample_size": { "type": "integer" }, "num_layers": { "type": "integer" }, "persist": { "type": "boolean" }, "rel": { "type": "string" }, "seed": { "type": "integer" }, "walk_length": { "type": "integer" }, "walks_per_node": { "type": "integer" }, "window_size": { "type": "integer" } }, "required": [ "rel", "feature_col" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Refused with 400 when vocab_size x embedding_dim exceeds 1,000,000 floats. persisted mirrors the request's persist flag.", "properties": { "embedding_dim": { "type": "integer" }, "embeddings": { "description": "Map of node primary-key label to its embedding vector (array of numbers).", "type": "object" }, "feature_dim": { "type": "integer" }, "final_loss": { "type": "number" }, "persisted": { "type": "boolean" }, "training_pairs": { "type": "integer" }, "vocab_size": { "type": "integer" } }, "required": [ "embeddings", "vocab_size", "training_pairs", "final_loss", "embedding_dim", "feature_dim", "persisted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Trains attribute-aware GraphSAGE node embeddings over a graph schema and optionally persists them for similarity search.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/graphsage/{rel}/topk": { "get": { "operationId": "graph_graphsage_topk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "k", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "metric", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "metric is cosine (default), dot, l2, or manhattan (alias l1); an unknown metric is 400. 400 when the query node is not in the persisted set. Answers 503 with a hint when no embeddings are persisted or the persisted set is degenerate.", "items": { "properties": { "pk": { "type": "string" }, "score": { "type": "number" } }, "required": [ "pk", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the nodes most similar to a given node using the persisted GraphSAGE embeddings.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/k-shortest": { "get": { "operationId": "graph_k_shortest", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "source", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "target", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "k", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "weight_col", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "k is capped at 50 (over the cap is 400). Without weight_col every edge costs 1; with it, each edge costs the named numeric column of the destination row. source and target are single-string primary keys; nodes lists primary-key labels, source first.", "properties": { "paths": { "items": { "properties": { "cost": { "type": "number" }, "nodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "nodes", "cost" ], "type": "object" }, "type": "array" } }, "required": [ "paths" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns up to k loop-free shortest paths between two nodes, ranked by cost.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/label_propagation": { "get": { "operationId": "graph_label_propagation", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_iter", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "seed", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "pk is the node's primary-key values as an array; nodes sharing a label form one community. max_iter defaults to 20; pass seed for a repeatable result.", "items": { "properties": { "label": { "type": "integer" }, "pk": { "items": {}, "type": "array" } }, "required": [ "label", "pk" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Groups the nodes of a graph schema into communities by label propagation.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/louvain": { "get": { "operationId": "graph_louvain", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "tolerance", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "max_levels", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Defaults: tolerance 0.0001 (finite, >= 0), max_levels 10 (> 0). The relation must target the same schema. Refused with 400 above 500,000 rows. Community ids are dense from 0, assigned in primary-key order.", "properties": { "communities": { "items": { "properties": { "community": { "type": "integer" }, "pk": { "type": "string" } }, "required": [ "pk", "community" ], "type": "object" }, "type": "array" } }, "required": [ "communities" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detects communities in a graph schema with the Louvain modularity algorithm.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/neighbors": { "get": { "operationId": "graph_neighbors", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Primary keys of the neighbour nodes.", "items": { "type": "string" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the one-hop neighbours of a node along a relation.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/node2vec": { "post": { "operationId": "graph_node2vec", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Defaults: walks_per_node 10, walk_length 80 (their product is capped at 10,000,000), window_size 5, negative_samples 5, dim 128 (max 1024), epochs 5, initial_lr 0.025, min_lr 0.0001 (must not exceed initial_lr), p 1.0, q 1.0, seed 0, persist false. persist=true also requires the schema DDL privilege. Graphs above 100,000 nodes are refused.", "properties": { "dim": { "type": "integer" }, "epochs": { "type": "integer" }, "initial_lr": { "type": "number" }, "min_lr": { "type": "number" }, "negative_samples": { "type": "integer" }, "p": { "type": "number" }, "persist": { "type": "boolean" }, "q": { "type": "number" }, "rel": { "type": "string" }, "seed": { "type": "integer" }, "walk_length": { "type": "integer" }, "walks_per_node": { "type": "integer" }, "window_size": { "type": "integer" } }, "required": [ "rel" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Refused with 400 when vocab_size x dim exceeds 1,000,000 floats. persisted is true only when persist was requested and the write succeeded.", "properties": { "dim": { "type": "integer" }, "embeddings": { "description": "Map of node primary-key label to its embedding vector (array of numbers).", "type": "object" }, "final_loss": { "type": "number" }, "persisted": { "type": "boolean" }, "training_pairs": { "type": "integer" }, "vocab_size": { "type": "integer" } }, "required": [ "embeddings", "vocab_size", "training_pairs", "final_loss", "dim", "persisted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Trains Node2Vec node embeddings over a graph schema and optionally persists them for similarity search.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/node2vec/{rel}/topk": { "get": { "operationId": "graph_node2vec_topk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "k", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "metric", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "metric is cosine (default), dot, l2, or manhattan (alias l1); an unknown metric is 400. k is silently capped at 100,000. 400 when the query node is not in the persisted set or the relation is unknown. Answers 503 with a hint when no embeddings are persisted.", "items": { "properties": { "pk": { "type": "string" }, "score": { "type": "number" } }, "required": [ "pk", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the nodes most similar to a given node using the persisted Node2Vec embeddings.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/pagerank": { "get": { "operationId": "graph_pagerank", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "nodes", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "damping", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "max_iter", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "tol", "required": false, "schema": { "type": "number" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "nodes is a comma-separated list of primary keys forming the ranked node set (edges leaving it are dropped). damping defaults to 0.85, max_iter to 100, tol to 1e-6.", "items": { "properties": { "pk": { "type": "string" }, "score": { "type": "number" } }, "required": [ "pk", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Scores a set of nodes by PageRank over a relation.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/path": { "get": { "operationId": "graph_path", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "src", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "dst", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "max_depth", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "truncated=true means the depth limit (default 3) stopped the search, so reachable=false is not proof of no route.", "properties": { "max_depth": { "type": "integer" }, "reachable": { "type": "boolean" }, "truncated": { "type": "boolean" } }, "required": [ "max_depth", "reachable", "truncated" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reports whether one node can reach another along a relation within a depth limit.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/random-walk": { "get": { "operationId": "graph_random_walk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "start", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "steps", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "seed", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "p", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "q", "required": false, "schema": { "type": "number" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "steps is capped at 1,000 (over the cap is 400). walk lists primary-key labels, start first, length <= steps + 1 (shorter when a node has no outgoing edge). Setting p or q (each finite and > 0; the unset one defaults to 1.0) switches to the biased walk. Same seed and graph give the same walk.", "properties": { "start": { "type": "string" }, "walk": { "items": { "type": "string" }, "type": "array" } }, "required": [ "start", "walk" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Performs a seeded random walk from a start node, optionally Node2Vec-biased.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/reverse": { "get": { "operationId": "graph_reverse", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Primary keys of the source nodes. Requires a bidirectional, non-edge-backed relation (400 otherwise); 502 when part of the cluster is unreachable.", "items": { "type": "string" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the nodes that point to a node along a relation (its inbound edges).", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/graph/{schema}/triangles": { "get": { "operationId": "graph_triangles", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rel", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One entry per triangle; a, b and c are the nodes' primary-key value arrays, each triangle emitted once with a < b < c. The relation is walked as undirected and must target the same schema.", "items": { "properties": { "a": { "items": {}, "type": "array" }, "b": { "items": {}, "type": "array" }, "c": { "items": {}, "type": "array" } }, "required": [ "a", "b", "c" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Enumerates every triangle in a graph schema's self-relation.", "tags": [ "graph" ] } }, "/v1/tenants/{tenant}/ingest/files/{schema}": { "post": { "operationId": "ingest_file", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "csv_has_header", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "chunk_size", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "description": "Exactly one part named 'file' (binary CSV or NDJSON); other parts are ignored. Format is taken from the 'format' query parameter, else the part's content type (text/csv, application/x-ndjson, application/jsonl), else the filename extension (.csv, .ndjson, .jsonl), else NDJSON if the first non-blank byte is '{'. CSV cells are coerced to the table's column types; an empty cell becomes null. No request body size limit.", "properties": { "file": { "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "format is 'csv' or 'ndjson'. Query: format accepts csv, ndjson, jsonl, json-lines (case-insensitive); csv_has_header defaults to true (false = columns matched by declaration order); chunk_size defaults to 5000, clamped to 1..50000. A failure mid-file leaves earlier chunks written.", "properties": { "chunks": { "type": "integer" }, "elapsed_ms": { "type": "integer" }, "format": { "type": "string" }, "rows_ingested": { "type": "integer" } }, "required": [ "rows_ingested", "chunks", "format", "elapsed_ms" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Uploads a CSV or NDJSON file as multipart form data and loads its rows into an existing table.", "tags": [ "ingest" ] } }, "/v1/tenants/{tenant}/ingest/mysql/sync": { "post": { "operationId": "mysql_ingest_sync", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "conn_url is a MySQL connection URL that carries the source database credentials: a write-only secret, never echoed back. The source host must be on the server's ingest allow-list (deny-all by default). tables must contain at least one entry.", "properties": { "conn_url": { "type": "string" }, "tables": { "items": { "description": "mode is one of: full, incremental. incremental requires updated_at_col and since_unix_ms. src_schema is the MySQL database name. primary_key overrides the source table's primary key.", "properties": { "dest_schema_id": { "type": "string" }, "mode": { "type": "string" }, "primary_key": { "items": { "type": "string" }, "type": "array" }, "since_unix_ms": { "type": "integer" }, "src_schema": { "type": "string" }, "src_table": { "type": "string" }, "updated_at_col": { "type": "string" } }, "required": [ "src_schema", "src_table", "dest_schema_id", "mode" ], "type": "object" }, "type": "array" } }, "required": [ "conn_url", "tables" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "One result per requested table, in request order.", "properties": { "results": { "items": { "description": "src is '.'. new_cursor_unix_ms is always present: null for mode=full, the next since_unix_ms for mode=incremental.", "properties": { "dest": { "type": "string" }, "new_cursor_unix_ms": { "type": "integer" }, "rows_synced": { "type": "integer" }, "src": { "type": "string" } }, "required": [ "src", "dest", "rows_synced", "new_cursor_unix_ms" ], "type": "object" }, "type": "array" } }, "required": [ "results" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Copies one or more tables from a MySQL database into the tenant, creating each destination table if it does not exist, in full or incremental mode.", "tags": [ "ingest" ] } }, "/v1/tenants/{tenant}/ingest/postgres/sync": { "post": { "operationId": "pg_ingest_sync", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The host in conn_url must be on the operator's allow-list, otherwise 403. tables must not be empty; tables sync in order and the first failure stops the request.", "properties": { "conn_url": { "type": "string" }, "tables": { "items": { "description": "mode is full or incremental; incremental requires updated_at_col and since_unix_ms (0 on the first run). The destination table is created from the source table when it is not registered.", "properties": { "dest_schema_id": { "type": "string" }, "mode": { "type": "string" }, "primary_key": { "items": { "type": "string" }, "type": "array" }, "since_unix_ms": { "type": "integer" }, "src_schema": { "type": "string" }, "src_table": { "type": "string" }, "updated_at_col": { "type": "string" } }, "required": [ "src_schema", "src_table", "dest_schema_id", "mode" ], "type": "object" }, "type": "array" } }, "required": [ "conn_url", "tables" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An unreachable or failing source database answers 502.", "properties": { "results": { "items": { "description": "new_cursor_unix_ms is null for a full sync; for an incremental sync it is the cursor to send as since_unix_ms next time.", "properties": { "dest": { "type": "string" }, "new_cursor_unix_ms": { "type": "integer" }, "rows_synced": { "type": "integer" }, "src": { "type": "string" } }, "required": [ "src", "dest", "rows_synced", "new_cursor_unix_ms" ], "type": "object" }, "type": "array" } }, "required": [ "results" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Copies tables from an allow-listed external PostgreSQL database into the tenant, as a full copy or an incremental sync.", "tags": [ "ingest" ] } }, "/v1/tenants/{tenant}/ingest/s3/sync": { "post": { "operationId": "s3_ingest_sync", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "schema is the destination table id and must exist. prefix defaults to '' (bucket root). format overrides per-object extension detection (csv or ndjson). csv_has_header defaults to true; chunk_size defaults to 5000. mode is one of: full (default), incremental (not yet supported, returns 400). The bucket must be on the server's ingest allow-list (deny-all by default); storage credentials are server-side and never sent in the request.", "properties": { "bucket": { "type": "string" }, "chunk_size": { "type": "integer" }, "csv_has_header": { "type": "boolean" }, "format": { "type": "string" }, "mode": { "type": "string" }, "prefix": { "type": "string" }, "schema": { "type": "string" } }, "required": [ "bucket", "schema" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "large_object_warning is true when any object exceeded 100 MB.", "properties": { "large_object_warning": { "type": "boolean" }, "objects_empty": { "type": "integer" }, "objects_ingested": { "type": "integer" }, "objects_listed": { "type": "integer" }, "objects_unsupported_format": { "type": "integer" }, "per_object": { "items": { "description": "format is one of: csv, ndjson, unsupported, empty. error is always present: null on success, the failure message otherwise.", "properties": { "bytes": { "type": "integer" }, "error": { "type": "string" }, "format": { "type": "string" }, "key": { "type": "string" }, "rows_ingested": { "type": "integer" } }, "required": [ "key", "bytes", "format", "rows_ingested", "error" ], "type": "object" }, "type": "array" }, "rows_ingested": { "type": "integer" } }, "required": [ "objects_listed", "objects_ingested", "objects_unsupported_format", "objects_empty", "rows_ingested", "large_object_warning", "per_object" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Loads every CSV and NDJSON object under a prefix of an S3-compatible object storage bucket into an existing table.", "tags": [ "ingest" ] } }, "/v1/tenants/{tenant}/migrations": { "get": { "operationId": "migrations_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "description": "state is one of Pending, Validating, Backfilling, CutoverPending, Completed, Aborting, Aborted, Rejected. stalled appears when an in-progress migration cannot complete: the table's schema changed underneath it, or its backfill stopped on an error it recorded. stalled_class names which: manifest_changed, backfill_key_changed, backfill_write_failed or backfill_read_failed.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "id": { "type": "string" }, "progress": { "description": "Backfill progress; chunks are 64-row units.", "properties": { "chunks_done": { "type": "integer" }, "chunks_total": { "type": "integer" }, "rows_seen": { "type": "integer" }, "rows_written": { "type": "integer" } }, "required": [ "rows_seen", "rows_written", "chunks_done", "chunks_total" ], "type": "object" }, "schema": { "type": "string" }, "stalled": { "type": "string" }, "stalled_class": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "state", "diff", "progress", "version_before", "version_after" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the tenant's online schema migrations that the caller may see.", "tags": [ "migrations" ] }, "post": { "operationId": "migrations_submit", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "schema is the table id; diff is applied in order. A second migration on a table that already has one in flight answers 400.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "schema": { "type": "string" } }, "required": [ "schema", "diff" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is one of Pending, Validating, Backfilling, CutoverPending, Completed, Aborting, Aborted, Rejected. stalled appears when an in-progress migration cannot complete: the table's schema changed underneath it, or its backfill stopped on an error it recorded. stalled_class names which: manifest_changed, backfill_key_changed, backfill_write_failed or backfill_read_failed.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "id": { "type": "string" }, "progress": { "description": "Backfill progress; chunks are 64-row units.", "properties": { "chunks_done": { "type": "integer" }, "chunks_total": { "type": "integer" }, "rows_seen": { "type": "integer" }, "rows_written": { "type": "integer" } }, "required": [ "rows_seen", "rows_written", "chunks_done", "chunks_total" ], "type": "object" }, "schema": { "type": "string" }, "stalled": { "type": "string" }, "stalled_class": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "state", "diff", "progress", "version_before", "version_after" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Starts an online schema migration that rewrites a table to its new shape in the background.", "tags": [ "migrations" ] } }, "/v1/tenants/{tenant}/migrations/_audit": { "get": { "operationId": "migrations_audit", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "description": "event is submit, cutover, abort or auto-cutover; at_secs is a Unix timestamp in seconds.", "properties": { "actor": { "type": "string" }, "at_secs": { "type": "integer" }, "event": { "type": "string" }, "id": { "type": "string" }, "schema": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "version_before", "version_after", "state", "at_secs", "actor", "event" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the audit log of migration state transitions for the tenant.", "tags": [ "migrations" ] } }, "/v1/tenants/{tenant}/migrations/{id}": { "get": { "operationId": "migrations_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is one of Pending, Validating, Backfilling, CutoverPending, Completed, Aborting, Aborted, Rejected. stalled appears when an in-progress migration cannot complete: the table's schema changed underneath it, or its backfill stopped on an error it recorded. stalled_class names which: manifest_changed, backfill_key_changed, backfill_write_failed or backfill_read_failed.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "id": { "type": "string" }, "progress": { "description": "Backfill progress; chunks are 64-row units.", "properties": { "chunks_done": { "type": "integer" }, "chunks_total": { "type": "integer" }, "rows_seen": { "type": "integer" }, "rows_written": { "type": "integer" } }, "required": [ "rows_seen", "rows_written", "chunks_done", "chunks_total" ], "type": "object" }, "schema": { "type": "string" }, "stalled": { "type": "string" }, "stalled_class": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "state", "diff", "progress", "version_before", "version_after" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the state and progress of one online schema migration.", "tags": [ "migrations" ] } }, "/v1/tenants/{tenant}/migrations/{id}/abort": { "post": { "operationId": "migrations_abort", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "force", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The migration after the abort: state is Aborted and progress is reset. Aborting after rows were rewritten by an irreversible operation answers 409; aborting a finished migration answers 400. A migration stopped because its rewrite would change a row's primary key aborts with nothing to undo when every row it rewrote was written under that key check; otherwise it answers 409 unless force=true, which aborts and returns forced_abort.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "forced_abort": { "description": "Present only on a forced abort: counts from a read-only scan of the table, taken after the abort, of rows the migration's rewrite would move to a different primary key. It reports and changes nothing.", "properties": { "rows_scanned": { "type": "integer" }, "rows_that_would_move": { "type": "integer" }, "rows_unkeyed": { "type": "integer" }, "targets_holding_the_rewrite": { "type": "integer" }, "targets_present": { "type": "integer" } }, "required": [ "rows_scanned", "rows_that_would_move", "rows_unkeyed", "targets_present", "targets_holding_the_rewrite" ], "type": "object" }, "id": { "type": "string" }, "progress": { "description": "Backfill progress; chunks are 64-row units.", "properties": { "chunks_done": { "type": "integer" }, "chunks_total": { "type": "integer" }, "rows_seen": { "type": "integer" }, "rows_written": { "type": "integer" } }, "required": [ "rows_seen", "rows_written", "chunks_done", "chunks_total" ], "type": "object" }, "schema": { "type": "string" }, "stalled": { "type": "string" }, "stalled_class": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "state", "diff", "progress", "version_before", "version_after" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Aborts an in-progress migration and restores the table's previous shape.", "tags": [ "migrations" ] } }, "/v1/tenants/{tenant}/migrations/{id}/cutover": { "post": { "operationId": "migrations_cutover", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is one of Pending, Validating, Backfilling, CutoverPending, Completed, Aborting, Aborted, Rejected. stalled appears when an in-progress migration cannot complete: the table's schema changed underneath it, or its backfill stopped on an error it recorded. stalled_class names which: manifest_changed, backfill_key_changed, backfill_write_failed or backfill_read_failed.", "properties": { "diff": { "items": { "description": "One diff operation, externally tagged: exactly one key, naming the operation.", "properties": { "AddColumn": { "properties": { "default": {}, "name": { "type": "string" }, "ty": { "type": "string" } }, "required": [ "name", "ty" ], "type": "object" }, "ChangeColumnType": { "properties": { "name": { "type": "string" }, "new_ty": { "type": "string" } }, "required": [ "name", "new_ty" ], "type": "object" }, "ChangeExtractionPath": { "properties": { "name": { "type": "string" }, "new_path": { "type": "string" } }, "required": [ "name", "new_path" ], "type": "object" }, "DropColumn": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "RenameColumn": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "SetColumnDefault": { "properties": { "default": {}, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetColumnNullability": { "properties": { "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "required" ], "type": "object" } }, "type": "object" }, "type": "array" }, "id": { "type": "string" }, "progress": { "description": "Backfill progress; chunks are 64-row units.", "properties": { "chunks_done": { "type": "integer" }, "chunks_total": { "type": "integer" }, "rows_seen": { "type": "integer" }, "rows_written": { "type": "integer" } }, "required": [ "rows_seen", "rows_written", "chunks_done", "chunks_total" ], "type": "object" }, "schema": { "type": "string" }, "stalled": { "type": "string" }, "stalled_class": { "type": "string" }, "state": { "type": "string" }, "tenant": { "type": "string" }, "version_after": { "type": "integer" }, "version_before": { "type": "integer" } }, "required": [ "id", "tenant", "schema", "state", "diff", "progress", "version_before", "version_after" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Switches a table over to its migrated shape and completes the migration.", "tags": [ "migrations" ] } }, "/v1/tenants/{tenant}/query": { "post": { "operationId": "query_exec", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "explain", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A query plan node tagged by op (snake_case operator name) with operator-specific fields; nested plans use the same shape. Write operators are refused with 400.", "properties": { "op": { "type": "string" } }, "required": [ "op" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "With ?explain set to any value other than false, 0, no or off, the body is instead an object {rows, explain} where explain is the measured plan tree. The X-OC-Query-Id response header names the query for cancellation; a statement timeout answers 408 and a cancelled query 499.", "items": { "description": "A row keyed by column name; the table's manifest defines the columns.", "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Executes a read query plan and returns the matching rows.", "tags": [ "query" ] } }, "/v1/tenants/{tenant}/query-metrics": { "get": { "operationId": "query_metrics", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "minutes", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "bucket_seconds", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Accepted minutes/bucket_seconds pairs are 60/60, 1440/600 and 10080/3600. schema_version is 1; scope is local-process; retention_seconds is 604800; dropped_events is 0 on successful reads. from, to and collection_started_at are Unix milliseconds. Coverage is clipped to collection start and retention, with no zeroes before collection began. Restart clears history. At most 64 active tenant windows are retained; a new read or completion after retirement starts an explicitly dated window, with 503 until any positive duration has been observed. A zero-duration window or incomplete counts return 503. Requires a tenant service credential or query administrator; impersonated database-user headers are refused. Reads do not open a store and do not count as queries. Latency measures execution-request completion and excludes preparation; PostgreSQL can execute SELECT preparation during Describe and reuse it in Execute, so that preparation work is outside this latency. This is a single-process view, not an aggregate across replicas.", "properties": { "bucket_seconds": { "type": "integer" }, "buckets": { "items": { "description": "at is the bucket start in Unix milliseconds. calls includes completed HTTP query requests and PostgreSQL, MySQL and TDS operations; preparation, description, session and index-administration operations are excluded. Counts are execution requests, not individual statements inside a batch. failed counts error, timeout and denied outcomes. mean_latency_ms is weighted by calls and is null when calls is zero. observed_seconds is the actual covered portion of this bucket, always positive; divide calls by it for throughput.", "properties": { "at": { "format": "int64", "type": "integer" }, "calls": { "format": "int64", "type": "integer" }, "failed": { "format": "int64", "type": "integer" }, "mean_latency_ms": { "type": [ "number", "null" ] }, "observed_seconds": { "type": "number" } }, "required": [ "at", "calls", "failed", "mean_latency_ms", "observed_seconds" ], "type": "object" }, "type": "array" }, "collection_started_at": { "format": "int64", "type": "integer" }, "dropped_events": { "format": "int64", "type": "integer" }, "from": { "format": "int64", "type": "integer" }, "retention_seconds": { "type": "integer" }, "schema_version": { "type": "integer" }, "scope": { "type": "string" }, "tenant_id": { "type": "string" }, "to": { "format": "int64", "type": "integer" } }, "required": [ "schema_version", "tenant_id", "from", "to", "bucket_seconds", "collection_started_at", "scope", "retention_seconds", "buckets", "dropped_events" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns tenant-scoped completion counts and mean latency from this running process, without storing query text or requiring remote telemetry enrollment.", "tags": [ "query-metrics" ] } }, "/v1/tenants/{tenant}/query-stats": { "get": { "operationId": "query_stats", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "since_unix (Unix seconds) is the start of the capture window. Fingerprints are sorted by total_us descending; at most 200 are kept. Writes are not recorded.", "properties": { "fingerprints": { "items": { "description": "lang is one of: sql, cypher, ask. fingerprint is the statement text with quoted strings and digit runs replaced by '?'. Latencies are microseconds; first_seen/last_seen are Unix seconds. cache_hit_rate (0..1) is omitted when the query path has no plan cache.", "properties": { "avg_rows": { "type": "number" }, "cache_hit_rate": { "type": "number" }, "count": { "type": "integer" }, "fingerprint": { "type": "string" }, "first_seen": { "type": "integer" }, "lang": { "type": "string" }, "last_seen": { "type": "integer" }, "max_us": { "type": "integer" }, "p50_us": { "type": "integer" }, "p95_us": { "type": "integer" }, "p99_us": { "type": "integer" }, "total_us": { "type": "integer" } }, "required": [ "fingerprint", "lang", "count", "p50_us", "p95_us", "p99_us", "max_us", "total_us", "avg_rows", "first_seen", "last_seen" ], "type": "object" }, "type": "array" }, "since_unix": { "type": "integer" } }, "required": [ "since_unix", "fingerprints" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns per-fingerprint statistics for the tenant's read queries (call count, latency percentiles, average rows and cache-hit rate), collected in memory since the server last started.", "tags": [ "query-stats" ] } }, "/v1/tenants/{tenant}/rows/{schema}": { "post": { "operationId": "rows_put", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expect", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "chunk", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "One row keyed by column name; the table's manifest defines the columns. With ?expect=insert an existing primary key is rejected with 409. Honors Idempotency-Key.", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "ok is always true. chunk is accepted but only affects the streaming batch endpoint.", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Writes one row, inserting it or replacing the row that has the same primary key.", "tags": [ "rows" ] } }, "/v1/tenants/{tenant}/rows/{schema}/_batch": { "post": { "operationId": "rows_put_batch", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expect", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "chunk", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON array (up to 64 MiB) is written atomically. Send Content-Type application/x-ndjson, application/jsonl or application/ndjson to stream one JSON row per line instead, committed in chunks of ?chunk rows (default 1000, max 10000). With ?expect=insert a duplicate primary key is rejected with 409. Honors Idempotency-Key.", "items": { "description": "One row keyed by column name.", "type": "object" }, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A newline-delimited stream that fails part-way answers 207 with inserted (rows already committed, which stay written) and error.", "properties": { "error": { "type": "string" }, "inserted": { "type": "integer" } }, "required": [ "inserted" ], "type": "object" } } }, "description": "OK" }, "207": { "content": { "application/json": { "schema": { "description": "A newline-delimited stream that fails part-way answers 207 with inserted (rows already committed, which stay written) and error.", "properties": { "error": { "type": "string" }, "inserted": { "type": "integer" } }, "required": [ "inserted" ], "type": "object" } } }, "description": "See the error body" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Writes many rows in one request, from a JSON array or a newline-delimited JSON stream.", "tags": [ "rows" ] } }, "/v1/tenants/{tenant}/rows/{schema}/{pk}": { "delete": { "operationId": "row_delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Honors the Idempotency-Key header. 409 when a restricting foreign key still references the row. Tables with a composite primary key are not path-addressable (400).", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes one row by primary key outside a transaction; deleting a missing row succeeds with deleted set to false.", "tags": [ "rows" ] }, "get": { "operationId": "row_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The stored row keyed by column name. Numeric columns render at their declared scale and masked columns are redacted. Composite primary keys are not addressable by path (400).", "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Fetches one row by its primary key.", "tags": [ "rows" ] }, "put": { "operationId": "row_put_cas", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "pk", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expect", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "chunk", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The full row as a JSON object keyed by column name; its primary key must match the path. Without an If-Match header this is an unconditional upsert. If-Match: (bare or quoted) requires the row to be at version n (its _oc_row_version); If-Match: * requires the row to exist. A stale version answers 409 write_conflict with current_version; a missing row answers 412 precondition_failed. Weak or list-valued If-Match is refused (400), as is ?expect=insert combined with If-Match. ?expect=insert alone makes the write insert-only. ?chunk is accepted but only affects NDJSON ingest. Honors Idempotency-Key.", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "version (the new row version, also returned as a quoted ETag header) is present only on a conditional write.", "properties": { "ok": { "type": "boolean" }, "version": { "type": "integer" } }, "required": [ "ok" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Writes one row by primary key, optionally as a compare-and-set against the row version given in If-Match.", "tags": [ "rows" ] } }, "/v1/tenants/{tenant}/schemas": { "delete": { "operationId": "schemas_delete_all", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "purge_rows", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Always 200 with this body on success. When confirmation is enforced and any table holds rows, a request without ?purge_rows=true answers 409 tenant_not_empty. On a multi-node cluster an unreachable node answers 502, before anything is erased or, if it fails mid-wipe, naming what was erased.", "properties": { "complete": { "type": "boolean" }, "deleted": { "type": "integer" }, "ids": { "items": { "type": "string" }, "type": "array" }, "irreversible": { "type": "boolean" }, "rows_deleted": { "type": "integer" } }, "required": [ "deleted", "ids", "rows_deleted", "complete", "irreversible" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes every table in the tenant and irreversibly purges all of their data.", "tags": [ "schemas" ] }, "get": { "operationId": "schemas_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Sorted table ids (namespace.table). On a multi-node cluster an unreachable node answers 502 rather than a partial list.", "items": { "type": "string" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the table ids registered for the tenant that the caller may see.", "tags": [ "schemas" ] }, "post": { "operationId": "schemas_register", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "text/plain; charset=utf-8": { "schema": { "description": "A TOML table manifest; the Content-Type header is not checked. Registering an id that already exists answers 409 (class schema_already_exists). Honors Idempotency-Key.", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "geo_fields lists the installed geo fields and appears only when the manifest declared a geo block.", "properties": { "geo_fields": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "tenant": { "type": "string" } }, "required": [ "id", "tenant" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Registers a new table from a TOML manifest.", "tags": [ "schemas" ] } }, "/v1/tenants/{tenant}/schemas/{id}": { "delete": { "operationId": "schemas_delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "purge_rows", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Answers 204 with no body unless rows were deleted and ?purge_rows=true was sent, in which case it answers 200 with this body. When confirmation is enforced, deleting a non-empty table without ?purge_rows=true answers 409 schema_not_empty and deletes nothing.", "properties": { "irreversible": { "type": "boolean" }, "keys_removed": { "type": "integer" }, "rows_deleted": { "type": "integer" }, "schema": { "type": "string" } }, "required": [ "schema", "rows_deleted", "keys_removed", "irreversible" ], "type": "object" } } }, "description": "OK" }, "204": { "description": "No content" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes one table and irreversibly purges all of its rows, indexes and related data.", "tags": [ "schemas" ] }, "get": { "operationId": "schemas_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "text/plain; charset=utf-8": { "schema": { "description": "The canonical TOML manifest, including synthesized defaults such as the primary-key index.", "type": "string" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the registered TOML manifest for one table.", "tags": [ "schemas" ] } }, "/v1/tenants/{tenant}/slow-queries": { "get": { "operationId": "slow_queries", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "threshold_ms", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "threshold_ms defaults to 0 (every recent execution). At most the 200 most recent executions are kept, in memory, since since_unix (Unix seconds).", "properties": { "entries": { "items": { "description": "lang is one of: sql, cypher, ask. ts is Unix seconds; elapsed_us is microseconds. text is the raw statement, truncated to 600 characters.", "properties": { "elapsed_us": { "type": "integer" }, "fingerprint": { "type": "string" }, "lang": { "type": "string" }, "rows": { "type": "integer" }, "text": { "type": "string" }, "ts": { "type": "integer" } }, "required": [ "ts", "elapsed_us", "lang", "rows", "fingerprint", "text" ], "type": "object" }, "type": "array" }, "since_unix": { "type": "integer" }, "threshold_ms": { "type": "integer" } }, "required": [ "since_unix", "threshold_ms", "entries" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the tenant's most recent read-query executions with their text and latency, newest first, optionally filtered to those at or above a latency threshold.", "tags": [ "slow-queries" ] } }, "/v1/tenants/{tenant}/sql": { "post": { "operationId": "sql_exec", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "params binds $1, $2, ... in order (any JSON values) and cannot be combined with a multi-statement batch; a batch holds at most 256 statements and runs as one implicit transaction. session_id pins the statement to the transaction a BEGIN opened, equivalent to the X-OC-Session-Id header. Optional headers: X-OC-Session-Id, X-OC-Statement-Timeout-Ms (408 on expiry), X-OC-Query-Id (client-chosen ULID, usable for cancellation; 409 if already running), X-OC-DB-User for database-user identity.", "properties": { "params": { "items": {}, "type": "array" }, "session_id": { "type": "string" }, "sql": { "type": "string" } }, "required": [ "sql" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A union tagged by kind; only the fields of that kind are present. select: rows, columns (projection order), column_types (PostgreSQL type of numeric/date/time/timestamp outputs, which arrive as strings). A NULL cell is an absent key, so read cells by name against columns. explain: plan, stats. insert: schema, inserted, updated/skipped (ON CONFLICT), returning + rows (RETURNING). update: schema, rows_affected, returning + rows. delete: schema, pk, rows_affected (or rows_buffered inside a transaction), returning + rows. buffered: schema, shard. tx: op (begin/commit/rollback/noop), ops_committed, session_id; a ROLLBACK or ROLLBACK TO SAVEPOINT that did not undo statements the block applied at once (schema changes, which apply at once inside a transaction block) adds applied_at_once ([{stmt}], in the order they ran) and message. Inside a transaction block, such a statement's own answer carries applied_at_once (itself) and message. batch: results plus stop/rollback fields. DDL kinds: createtable, droptable, droptable_accepted (answered with HTTP 202; poll the status path), truncate, createindex, dropindex, altertable, createview, dropview, creatematerializedview, refreshmaterializedview, dropmaterializedview, createsequence, dropsequence, createschema, dropschema, createextension, createprocedure, dropprocedure, createfunction, dropfunction, createtrigger, droptrigger. Also set, maintenance (VACUUM/ANALYZE, a no-op), and grant/revoke (the access-control response body tagged with kind).", "properties": { "applied": { "type": "boolean" }, "applied_at_once": { "items": { "properties": { "stmt": { "type": "string" } }, "required": [ "stmt" ], "type": "object" }, "type": "array" }, "column_types": { "type": "object" }, "columns": { "items": { "type": "string" }, "type": "array" }, "command": { "type": "string" }, "commit_points": { "items": { "properties": { "before_statement": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "before_statement", "reason" ], "type": "object" }, "type": "array" }, "committed_through": { "type": "integer" }, "created": { "type": "boolean" }, "dropped": { "type": "boolean" }, "entries_swept": { "type": "integer" }, "error": { "type": "string" }, "events": { "items": { "type": "string" }, "type": "array" }, "existed": { "type": "boolean" }, "extension": { "type": "string" }, "failed_status": { "type": "integer" }, "index": { "type": "string" }, "inserted": { "type": "integer" }, "kind": { "type": "string" }, "message": { "type": "string" }, "migration": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "notice": { "type": "string" }, "op": { "type": "string" }, "ops": { "type": "integer" }, "ops_committed": { "type": "integer" }, "outcome_unknown": { "type": "boolean" }, "pk": { "type": "string" }, "plan": { "type": "string" }, "reclaim": { "description": "The reclamation job record. state is pending, running or complete; phase is one of sparse_inverted, row_layer, vector, fts_geo, mv, catalog, finalize, done. started_ms/updated_ms are Unix epoch milliseconds.", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "keys_removed": { "type": "integer" }, "phase": { "type": "string" }, "reclaim_queued": { "type": "boolean" }, "rounds": { "type": "integer" }, "row_cursor_set": { "type": "boolean" }, "row_layer_keys_removed": { "type": "integer" }, "rows_before": { "type": "integer" }, "rows_before_exact": { "type": "boolean" }, "rows_deleted": { "type": "integer" }, "rows_removed": { "type": "integer" }, "schema": { "type": "string" }, "started_ms": { "type": "integer" }, "state": { "type": "string" }, "updated_ms": { "type": "integer" } }, "required": [ "schema", "phase", "state", "keys_removed", "row_layer_keys_removed", "reclaim_queued", "rows_before", "rows_before_exact", "rows_removed", "rows_deleted", "row_cursor_set", "rounds", "started_ms", "updated_ms", "actor", "action" ], "type": "object" }, "refresh_mode": { "type": "string" }, "relations": { "items": { "type": "string" }, "type": "array" }, "replaced": { "type": "boolean" }, "results": { "items": { "description": "One full /sql response per executed statement, in submission order.", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "type": "array" }, "returning": { "items": { "type": "string" }, "type": "array" }, "rolled_back": { "type": "boolean" }, "rows": { "items": { "description": "A user row keyed by column name; cell values are user data.", "type": "object" }, "type": "array" }, "rows_affected": { "type": "integer" }, "rows_buffered": { "type": "integer" }, "rows_deleted": { "type": "integer" }, "rows_exact": { "type": "boolean" }, "rows_indexed": { "type": "integer" }, "rows_materialized": { "type": "integer" }, "rows_probed": { "type": "integer" }, "schema": { "type": "string" }, "sequence": { "type": "string" }, "session_id": { "type": "string" }, "setting": { "type": "string" }, "shard": { "type": "integer" }, "skipped": { "type": "integer" }, "sqlstate": { "type": "string" }, "state": { "type": "string" }, "stats": { "type": "object" }, "status": { "type": "string" }, "stopped_on_error": { "type": "boolean" }, "sweep_complete": { "type": "boolean" }, "tables_dropped": { "type": "integer" }, "timing": { "type": "string" }, "trigger": { "type": "string" }, "updated": { "type": "integer" }, "view": { "type": "string" } }, "required": [ "kind" ], "type": "object" } } }, "description": "OK" }, "202": { "content": { "application/json": { "schema": { "description": "A union tagged by kind; only the fields of that kind are present. select: rows, columns (projection order), column_types (PostgreSQL type of numeric/date/time/timestamp outputs, which arrive as strings). A NULL cell is an absent key, so read cells by name against columns. explain: plan, stats. insert: schema, inserted, updated/skipped (ON CONFLICT), returning + rows (RETURNING). update: schema, rows_affected, returning + rows. delete: schema, pk, rows_affected (or rows_buffered inside a transaction), returning + rows. buffered: schema, shard. tx: op (begin/commit/rollback/noop), ops_committed, session_id; a ROLLBACK or ROLLBACK TO SAVEPOINT that did not undo statements the block applied at once (schema changes, which apply at once inside a transaction block) adds applied_at_once ([{stmt}], in the order they ran) and message. Inside a transaction block, such a statement's own answer carries applied_at_once (itself) and message. batch: results plus stop/rollback fields. DDL kinds: createtable, droptable, droptable_accepted (answered with HTTP 202; poll the status path), truncate, createindex, dropindex, altertable, createview, dropview, creatematerializedview, refreshmaterializedview, dropmaterializedview, createsequence, dropsequence, createschema, dropschema, createextension, createprocedure, dropprocedure, createfunction, dropfunction, createtrigger, droptrigger. Also set, maintenance (VACUUM/ANALYZE, a no-op), and grant/revoke (the access-control response body tagged with kind).", "properties": { "applied": { "type": "boolean" }, "applied_at_once": { "items": { "properties": { "stmt": { "type": "string" } }, "required": [ "stmt" ], "type": "object" }, "type": "array" }, "column_types": { "type": "object" }, "columns": { "items": { "type": "string" }, "type": "array" }, "command": { "type": "string" }, "commit_points": { "items": { "properties": { "before_statement": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "before_statement", "reason" ], "type": "object" }, "type": "array" }, "committed_through": { "type": "integer" }, "created": { "type": "boolean" }, "dropped": { "type": "boolean" }, "entries_swept": { "type": "integer" }, "error": { "type": "string" }, "events": { "items": { "type": "string" }, "type": "array" }, "existed": { "type": "boolean" }, "extension": { "type": "string" }, "failed_status": { "type": "integer" }, "index": { "type": "string" }, "inserted": { "type": "integer" }, "kind": { "type": "string" }, "message": { "type": "string" }, "migration": { "type": "string" }, "name": { "type": "string" }, "note": { "type": "string" }, "notice": { "type": "string" }, "op": { "type": "string" }, "ops": { "type": "integer" }, "ops_committed": { "type": "integer" }, "outcome_unknown": { "type": "boolean" }, "pk": { "type": "string" }, "plan": { "type": "string" }, "reclaim": { "description": "The reclamation job record. state is pending, running or complete; phase is one of sparse_inverted, row_layer, vector, fts_geo, mv, catalog, finalize, done. started_ms/updated_ms are Unix epoch milliseconds.", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "keys_removed": { "type": "integer" }, "phase": { "type": "string" }, "reclaim_queued": { "type": "boolean" }, "rounds": { "type": "integer" }, "row_cursor_set": { "type": "boolean" }, "row_layer_keys_removed": { "type": "integer" }, "rows_before": { "type": "integer" }, "rows_before_exact": { "type": "boolean" }, "rows_deleted": { "type": "integer" }, "rows_removed": { "type": "integer" }, "schema": { "type": "string" }, "started_ms": { "type": "integer" }, "state": { "type": "string" }, "updated_ms": { "type": "integer" } }, "required": [ "schema", "phase", "state", "keys_removed", "row_layer_keys_removed", "reclaim_queued", "rows_before", "rows_before_exact", "rows_removed", "rows_deleted", "row_cursor_set", "rounds", "started_ms", "updated_ms", "actor", "action" ], "type": "object" }, "refresh_mode": { "type": "string" }, "relations": { "items": { "type": "string" }, "type": "array" }, "replaced": { "type": "boolean" }, "results": { "items": { "description": "One full /sql response per executed statement, in submission order.", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "type": "array" }, "returning": { "items": { "type": "string" }, "type": "array" }, "rolled_back": { "type": "boolean" }, "rows": { "items": { "description": "A user row keyed by column name; cell values are user data.", "type": "object" }, "type": "array" }, "rows_affected": { "type": "integer" }, "rows_buffered": { "type": "integer" }, "rows_deleted": { "type": "integer" }, "rows_exact": { "type": "boolean" }, "rows_indexed": { "type": "integer" }, "rows_materialized": { "type": "integer" }, "rows_probed": { "type": "integer" }, "schema": { "type": "string" }, "sequence": { "type": "string" }, "session_id": { "type": "string" }, "setting": { "type": "string" }, "shard": { "type": "integer" }, "skipped": { "type": "integer" }, "sqlstate": { "type": "string" }, "state": { "type": "string" }, "stats": { "type": "object" }, "status": { "type": "string" }, "stopped_on_error": { "type": "boolean" }, "sweep_complete": { "type": "boolean" }, "tables_dropped": { "type": "integer" }, "timing": { "type": "string" }, "trigger": { "type": "string" }, "updated": { "type": "integer" }, "view": { "type": "string" } }, "required": [ "kind" ], "type": "object" } } }, "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Executes a SQL statement or a semicolon-separated batch and returns rows for queries or a result summary for writes and DDL.", "tags": [ "sql" ] } }, "/v1/tenants/{tenant}/sql/materialized-views": { "get": { "operationId": "mv_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Sorted by name. Only views over tables the caller may read are listed. On a multi-node cluster this lists the views homed on the answering node.", "items": { "description": "refresh_mode is on_demand or incremental; source_schema is the base table \"namespace.table\"; warming is true while an incremental aggregate view is still being reconciled after a restart.", "properties": { "name": { "type": "string" }, "refresh_mode": { "type": "string" }, "source_schema": { "type": "string" }, "warming": { "type": "boolean" } }, "required": [ "name", "refresh_mode", "source_schema", "warming" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the materialized views installed for the tenant with their refresh mode and base table.", "tags": [ "sql" ] }, "post": { "operationId": "mv_install", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "refresh_mode is \"on_demand\" (default; stale until refreshed) or \"incremental\" (maintained on every write; only filter/projection views and COUNT/SUM/AVG rollups qualify, otherwise 422). source_schema optionally names the base table as \"namespace.table\" and must agree with the query's FROM. auto=true chooses incremental when the query shape allows it and on_demand otherwise. 409 when the name already exists.", "properties": { "name": { "type": "string" }, "query": { "type": "string" }, "refresh_mode": { "type": "string" }, "source_schema": { "type": "string" } }, "required": [ "name", "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "bytes_written": { "type": "integer" }, "name": { "type": "string" }, "refresh_ts": { "type": "integer" }, "rows_materialized": { "type": "integer" } }, "required": [ "name", "rows_materialized", "bytes_written", "refresh_ts" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates a materialized view from a SQL SELECT and materializes its initial contents.", "tags": [ "sql" ] } }, "/v1/tenants/{tenant}/sql/materialized-views/{name}": { "delete": { "operationId": "mv_drop", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "404 when the view does not exist. Irreversible; recorded in the destructive-operation audit trail.", "properties": { "dropped": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name", "dropped" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Drops a materialized view and everything stored for it.", "tags": [ "sql" ] }, "get": { "operationId": "mv_read", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "For an aggregate view each row is one group's output columns. A view whose incremental maintenance is not running is recomputed from its base table instead of serving stale rows.", "properties": { "name": { "type": "string" }, "rows": { "items": { "description": "A user row keyed by column name; cell values are user data.", "type": "object" }, "type": "array" } }, "required": [ "name", "rows" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the rows of a materialized view, filtered and masked by the caller's row-level policies.", "tags": [ "sql" ] } }, "/v1/tenants/{tenant}/sql/materialized-views/{name}/refresh": { "post": { "operationId": "mv_refresh", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "422 when the view is incremental and its maintenance is disabled on this server. The request body must be empty.", "properties": { "bytes_written": { "type": "integer" }, "name": { "type": "string" }, "refresh_ts": { "type": "integer" }, "rows_materialized": { "type": "integer" } }, "required": [ "name", "rows_materialized", "bytes_written", "refresh_ts" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Recomputes a materialized view from its base table and replaces its stored rows.", "tags": [ "sql" ] } }, "/v1/tenants/{tenant}/tx/begin": { "post": { "operationId": "tx_begin", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "isolation", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body is optional and may be empty. isolation is \"snapshot_isolation\" (default) or \"serializable\"; it may instead be sent as ?isolation=, and the two must agree. Misspellings such as isolation_level are refused with 400. Serializable is refused (501) on a sharded database.", "properties": { "isolation": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "isolation echoes the level actually in force. serializable_scope (\"point_reads_only\") is present only when the serializable guarantee covers point reads only, in which case in-transaction queries are refused.", "properties": { "_preview": { "type": "boolean" }, "isolation": { "type": "string" }, "read_ts": { "type": "integer" }, "serializable_scope": { "type": "string" }, "tx_id": { "type": "string" } }, "required": [ "tx_id", "read_ts", "isolation", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Opens a multi-statement transaction at snapshot or serializable isolation and returns its id.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}": { "get": { "operationId": "tx_status", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is one of active, committing, committed, rolled_back, conflict, expired; isolation is snapshot_isolation or serializable. A transaction owned by another identity answers 404.", "properties": { "_preview": { "type": "boolean" }, "isolation": { "type": "string" }, "read_ts": { "type": "integer" }, "state": { "type": "string" }, "tx_id": { "type": "string" } }, "required": [ "tx_id", "read_ts", "state", "isolation", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the current state, snapshot tick and isolation level of a transaction.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}/commit": { "post": { "operationId": "tx_commit", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "lsn is null on multi-writer databases, where durability is quorum-based. A 409 carries error tx_conflict, serialization_failure or constraint_violation; the transaction is then terminal and must be retried from begin. The request body must be empty.", "properties": { "_preview": { "type": "boolean" }, "committed": { "type": "boolean" }, "lsn": { "properties": { "offset": { "type": "integer" }, "segment": { "type": "integer" } }, "required": [ "segment", "offset" ], "type": "object" }, "tx_id": { "type": "string" } }, "required": [ "committed", "tx_id", "lsn", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Atomically commits every write buffered in the transaction, enforcing foreign-key, check and unique constraints.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}/query": { "post": { "operationId": "tx_query", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A query plan tree tagged by op, e.g. {\"op\":\"scan\",\"schema\":\"ns.table\"}, optionally wrapped in filter, project, sort, limit, distinct, aggregate, window, join, set-operation or CTE nodes. Plans that read outside a full-table scan (index scans, count fast paths, graph traversals) and write plans are refused with 400.", "properties": { "op": { "type": "string" } }, "required": [ "op" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Rows are filtered and masked by the caller's row-level policies.", "properties": { "_preview": { "type": "boolean" }, "rows": { "items": { "description": "A user row keyed by column name; cell values are user data.", "type": "object" }, "type": "array" }, "tx_id": { "type": "string" } }, "required": [ "rows", "tx_id", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs a read-only query plan inside the transaction at its snapshot, including the transaction's own buffered writes.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}/rollback": { "post": { "operationId": "tx_rollback", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "409 when the transaction is no longer active. The request body must be empty.", "properties": { "_preview": { "type": "boolean" }, "rolled_back": { "type": "boolean" }, "tx_id": { "type": "string" } }, "required": [ "rolled_back", "tx_id", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Discards every write buffered in the transaction and closes it.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}/rows/{schema}": { "post": { "operationId": "tx_row_put", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The row as a JSON object keyed by column name, including its primary key. Columns are user-defined by the table. Shape and types are validated now (400); constraints are enforced at commit.", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "op is \"put\"; buffered is always true. 413 when the transaction already holds its maximum of buffered operations.", "properties": { "_preview": { "type": "boolean" }, "buffered": { "type": "boolean" }, "op": { "type": "string" }, "tx_id": { "type": "string" } }, "required": [ "tx_id", "op", "buffered", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Buffers an insert-or-replace of one row in the transaction; it becomes visible to others only after commit.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/tx/{tx_id}/rows/{schema}/{pk}": { "delete": { "operationId": "tx_row_delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "op is \"delete\"; buffered is always true. Deleting a row that does not exist is a no-op at commit. Tables with a composite primary key are not path-addressable (400).", "properties": { "_preview": { "type": "boolean" }, "buffered": { "type": "boolean" }, "op": { "type": "string" }, "tx_id": { "type": "string" } }, "required": [ "tx_id", "op", "buffered", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Buffers the deletion of one row, addressed by primary key, in the transaction.", "tags": [ "tx" ] }, "get": { "operationId": "tx_row_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tx_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "schema", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "pk", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "404 when the row is absent at the snapshot, deleted by this transaction, or hidden by a row-level policy.", "properties": { "_preview": { "type": "boolean" }, "row": { "description": "A user row keyed by column name; cell values are user data.", "type": "object" }, "tx_id": { "type": "string" } }, "required": [ "row", "tx_id", "_preview" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reads one row by primary key at the transaction's snapshot, seeing the transaction's own buffered writes first.", "tags": [ "tx" ] } }, "/v1/tenants/{tenant}/usage": { "get": { "operationId": "usage", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "tier, configuration and limits are omitted when the tenant has no configuration set. The schemas breakdown is narrowed to tables the caller may read; totals stay whole-tenant. On a multi-node cluster an unreachable node answers 502.", "properties": { "addon_calls": { "items": { "properties": { "addon": { "type": "string" }, "allowed": { "type": "integer" }, "rejected": { "type": "integer" } }, "required": [ "addon", "allowed", "rejected" ], "type": "object" }, "type": "array" }, "configuration": { "properties": { "ha": { "type": "boolean" }, "label": { "type": "string" }, "monthly_price": { "type": "integer" }, "ram_gb": { "type": "integer" }, "slug": { "type": "string" }, "storage_gb": { "type": "integer" }, "vcpu": { "type": "integer" } }, "required": [ "slug", "label", "ha" ], "type": "object" }, "limits": { "properties": { "burst_rps": { "type": "integer" }, "concurrent_ask_cap": { "type": "integer" }, "graph_edges_cap": { "type": "integer" }, "graph_nodes_cap": { "type": "integer" }, "max_connections": { "type": "integer" }, "reactive_subscriptions_cap": { "type": "integer" }, "storage_gb": { "type": "integer" }, "sustained_rps": { "type": "integer" }, "vector_embeddings_cap": { "type": "integer" } }, "required": [ "storage_gb", "sustained_rps", "burst_rps", "max_connections", "vector_embeddings_cap", "graph_nodes_cap", "graph_edges_cap", "reactive_subscriptions_cap", "concurrent_ask_cap" ], "type": "object" }, "meter": { "description": "An empty object means the usage meter is healthy; when degraded, limits are reported but not enforced.", "properties": { "degraded": { "type": "string" }, "detail": { "type": "string" } }, "type": "object" }, "schemas": { "items": { "properties": { "bytes": { "type": "integer" }, "rows": { "type": "integer" }, "schema": { "type": "string" }, "segments": { "type": "integer" } }, "required": [ "schema", "rows", "bytes", "segments" ], "type": "object" }, "type": "array" }, "tenant": { "type": "string" }, "tier": { "type": "string" }, "used": { "description": "max_connections is always null. Graph counts lag until reconciled.", "properties": { "ask_in_flight": { "type": "integer" }, "graph_counts_reconciled": { "type": "boolean" }, "graph_edges": { "type": "integer" }, "graph_nodes": { "type": "integer" }, "max_connections": { "const": null }, "reactive_subscriptions": { "type": "integer" }, "storage_bytes": { "type": "integer" }, "store_keys": { "type": "integer" }, "vector_counter_lost_bumps": { "type": "integer" }, "vector_embeddings": { "type": "integer" } }, "required": [ "store_keys", "storage_bytes", "graph_nodes", "graph_edges", "graph_counts_reconciled", "max_connections", "vector_counter_lost_bumps", "ask_in_flight", "vector_embeddings", "reactive_subscriptions" ], "type": "object" } }, "required": [ "tenant", "meter", "used", "schemas", "addon_calls" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the tenant's configuration, limits and live usage counters.", "tags": [ "usage" ] } }, "/v1/tenants/{tenant}/vector-indexes": { "post": { "operationId": "create_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "name is 1-45 bytes of [a-z0-9-]. At least one of dimension, sparse: true or text_fields is required; dimension 1-8192 needs metric (cosine, dot, l2, manhattan). deletion_protection: enabled|disabled (default disabled); identifier_profile: unicode|ascii (default unicode); tags: string map, at most 20. embedding is refused with 501 and metadata_publish with 400 (generated-embedding indexes are not available yet). Unknown fields are refused with 400 unknown_request_field.", "properties": { "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "type": "object" }, "identifier_profile": { "type": "string" }, "metadata_publish": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "sparse": { "type": "boolean" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "description": "201 with the index object. state is active or deleting; metric is cosine, dot, l2 or manhattan (omitted with dimension for an index without dense vectors); score_direction is always higher_is_better; deletion_protection is enabled or disabled; identifier_profile is unicode or ascii; compat_family is documents, records, vectors or none; embedding is always present and null today; created_at is RFC 3339 UTC with milliseconds.", "properties": { "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "description": "Generated-embedding configuration; revision may be null. Indexes with generated embeddings cannot be created yet, so this is null in practice.", "properties": { "dimension": { "type": "integer" }, "document_task": { "type": "string" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "model_config_id": { "type": "string" }, "preprocessing_version": { "type": "string" }, "provider": { "type": "string" }, "query_task": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "model_config_id", "provider", "model", "revision", "dimension", "dtype", "metric", "preprocessing_version", "document_task", "query_task" ], "type": "object" }, "identifier_profile": { "type": "string" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "state": { "type": "string" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "index_id", "name", "state", "score_direction", "sparse", "text_fields", "visibility_fields", "embedding", "deletion_protection", "tags", "identifier_profile", "compat_family", "created_at" ], "type": "object" } } }, "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates a vector index with its dense, sparse and text configuration, holding an empty default namespace.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/list": { "post": { "operationId": "list_indexes", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "name is an exact lookup (no pages, not combinable with prefix or cursor); prefix is 1-45 bytes of [a-z0-9-]; limit 1-100, default 100. Send {} to list everything.", "properties": { "cursor": { "type": "string" }, "limit": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "next_cursor is present only when more indexes may follow.", "properties": { "indexes": { "items": { "description": "state is active or deleting; metric is cosine, dot, l2 or manhattan (omitted with dimension for an index without dense vectors); score_direction is always higher_is_better; deletion_protection is enabled or disabled; identifier_profile is unicode or ascii; compat_family is documents, records, vectors or none; embedding is always present and null today; created_at is RFC 3339 UTC with milliseconds.", "properties": { "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "description": "Generated-embedding configuration; revision may be null. Indexes with generated embeddings cannot be created yet, so this is null in practice.", "properties": { "dimension": { "type": "integer" }, "document_task": { "type": "string" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "model_config_id": { "type": "string" }, "preprocessing_version": { "type": "string" }, "provider": { "type": "string" }, "query_task": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "model_config_id", "provider", "model", "revision", "dimension", "dtype", "metric", "preprocessing_version", "document_task", "query_task" ], "type": "object" }, "identifier_profile": { "type": "string" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "state": { "type": "string" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "index_id", "name", "state", "score_direction", "sparse", "text_fields", "visibility_fields", "embedding", "deletion_protection", "tags", "identifier_profile", "compat_family", "created_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "indexes" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the vector indexes the caller can see, in name order, with cursor pagination.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index_id}/search": { "post": { "operationId": "search", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "mode: semantic, lexical, hybrid or dense_with_text_filter. k is 1 up to the engine's limit (default 10,000). include_components defaults to true, the other include_* to false. Not yet served (501): expected_generation, timeout_ms, text_fields, a projection on a plan with a lexical leg, fusion weighted_sum and mode dense_with_text_filter. Unknown fields at any depth answer 400 unknown_request_field.", "properties": { "dense": { "description": "Query by vector or by the id of a stored record. quality: exact, fast or high_recall (default).", "properties": { "candidates": { "type": "integer" }, "quality": { "type": "string" }, "record_id": { "type": "string" }, "vector": { "items": { "type": "number" }, "type": "array" } }, "type": "object" }, "expected_generation": { "type": "string" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "fusion": { "description": "method: rrf (optional rrf_k, default 60) or weighted_sum (weights required; currently answers 501).", "properties": { "method": { "type": "string" }, "rrf_k": { "type": "integer" }, "weights": { "properties": { "dense": { "type": "number" }, "sparse": { "type": "number" } }, "required": [ "dense", "sparse" ], "type": "object" } }, "required": [ "method" ], "type": "object" }, "include_components": { "type": "boolean" }, "include_metadata": { "type": "boolean" }, "include_sparse": { "type": "boolean" }, "include_values": { "type": "boolean" }, "k": { "type": "integer" }, "lexical": { "description": "match: terms (default) or phrase. query is at most 4,096 bytes and must not be blank.", "properties": { "candidates": { "type": "integer" }, "field": { "type": "string" }, "match": { "type": "string" }, "query": { "type": "string" } }, "required": [ "field", "query" ], "type": "object" }, "metadata_fields": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "namespace": { "type": "string" }, "require_complete": { "type": "boolean" }, "sparse": { "description": "scorer: cosine or dot. At most 1,024 non-zero entries.", "properties": { "candidates": { "type": "integer" }, "indices": { "items": { "type": "integer" }, "type": "array" }, "scorer": { "type": "string" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text_fields": { "items": { "type": "string" }, "type": "array" }, "timeout_ms": { "type": "integer" } }, "required": [ "namespace", "mode", "k" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "ranking_method is dense_similarity, sparse_cosine, sparse_dot, bm25 or rrf. Search is not paginated; a response over 4 MB is refused with 413.", "properties": { "completeness": { "description": "value is e.g. exact, exhausted or ann_underfilled; reason and examined accompany ann_underfilled (examined only for unrestricted callers).", "properties": { "examined": { "type": "integer" }, "reason": { "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "fusion": { "properties": { "method": { "type": "string" }, "rank_base": { "type": "integer" }, "rrf_k": { "type": "integer" }, "tie_break": { "type": "string" }, "weights": { "properties": { "dense": { "type": "number" }, "sparse": { "type": "number" } }, "required": [ "dense", "sparse" ], "type": "object" } }, "required": [ "method", "rank_base", "tie_break" ], "type": "object" }, "hits": { "items": { "description": "components appear when include_components is true (the default); values, sparse_values and metadata only when requested.", "properties": { "components": { "items": { "properties": { "leg": { "type": "string" }, "rank": { "type": "integer" }, "score": { "type": "number" } }, "required": [ "leg", "rank", "score" ], "type": "object" }, "type": "array" }, "id": { "type": "string" }, "metadata": { "type": "object" }, "rank": { "type": "integer" }, "score": { "type": "number" }, "sparse_values": { "properties": { "indices": { "items": { "type": "integer" }, "type": "array" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text": { "type": "object" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "id", "score", "rank" ], "type": "object" }, "type": "array" }, "index_id": { "type": "string" }, "k": { "type": "integer" }, "legs": { "items": { "properties": { "analysis": { "properties": { "input_tokens": { "type": "integer" }, "retained_tokens": { "type": "integer" } }, "required": [ "input_tokens", "retained_tokens" ], "type": "object" }, "analyzer": { "type": "string" }, "candidates_requested": { "type": "integer" }, "candidates_returned": { "type": "integer" }, "completeness": { "description": "value is e.g. exact, exhausted or ann_underfilled; reason and examined accompany ann_underfilled (examined only for unrestricted callers).", "properties": { "examined": { "type": "integer" }, "reason": { "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "field": { "type": "string" }, "index_kind": { "type": "string" }, "leg": { "type": "string" }, "quality": { "type": "string" }, "score_direction": { "type": "string" }, "score_range": { "type": "string" }, "scorer": { "type": "string" }, "statistics_scope": { "type": "string" } }, "required": [ "leg", "scorer", "score_direction", "index_kind", "candidates_requested", "candidates_returned", "completeness" ], "type": "object" }, "type": "array" }, "mode": { "type": "string" }, "namespace": { "type": "string" }, "ranking_method": { "type": "string" }, "read": { "properties": { "position": { "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "restore_epoch": { "properties": { "counter": { "type": "integer" } }, "required": [ "counter" ], "type": "object" } }, "required": [ "position", "restore_epoch" ], "type": "object" }, "returned": { "type": "integer" } }, "required": [ "index_id", "namespace", "mode", "ranking_method", "k", "returned", "completeness", "legs", "hits", "read" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Searches a namespace of a vector index with dense, sparse, lexical or hybrid ranking and an optional metadata filter.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}": { "delete": { "operationId": "delete_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "202": { "content": { "application/json": { "schema": { "description": "202 with the index object in state deleting. state is active or deleting; metric is cosine, dot, l2 or manhattan (omitted with dimension for an index without dense vectors); score_direction is always higher_is_better; deletion_protection is enabled or disabled; identifier_profile is unicode or ascii; compat_family is documents, records, vectors or none; embedding is always present and null today; created_at is RFC 3339 UTC with milliseconds.", "properties": { "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "description": "Generated-embedding configuration; revision may be null. Indexes with generated embeddings cannot be created yet, so this is null in practice.", "properties": { "dimension": { "type": "integer" }, "document_task": { "type": "string" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "model_config_id": { "type": "string" }, "preprocessing_version": { "type": "string" }, "provider": { "type": "string" }, "query_task": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "model_config_id", "provider", "model", "revision", "dimension", "dtype", "metric", "preprocessing_version", "document_task", "query_task" ], "type": "object" }, "identifier_profile": { "type": "string" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "state": { "type": "string" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "index_id", "name", "state", "score_direction", "sparse", "text_fields", "visibility_fields", "embedding", "deletion_protection", "tags", "identifier_profile", "compat_family", "created_at" ], "type": "object" } } }, "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes a vector index; its namespaces are erased in the background.", "tags": [ "vector-indexes" ] }, "get": { "operationId": "describe_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is active or deleting; metric is cosine, dot, l2 or manhattan (omitted with dimension for an index without dense vectors); score_direction is always higher_is_better; deletion_protection is enabled or disabled; identifier_profile is unicode or ascii; compat_family is documents, records, vectors or none; embedding is always present and null today; created_at is RFC 3339 UTC with milliseconds.", "properties": { "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "description": "Generated-embedding configuration; revision may be null. Indexes with generated embeddings cannot be created yet, so this is null in practice.", "properties": { "dimension": { "type": "integer" }, "document_task": { "type": "string" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "model_config_id": { "type": "string" }, "preprocessing_version": { "type": "string" }, "provider": { "type": "string" }, "query_task": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "model_config_id", "provider", "model", "revision", "dimension", "dtype", "metric", "preprocessing_version", "document_task", "query_task" ], "type": "object" }, "identifier_profile": { "type": "string" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "state": { "type": "string" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "index_id", "name", "state", "score_direction", "sparse", "text_fields", "visibility_fields", "embedding", "deletion_protection", "tags", "identifier_profile", "compat_family", "created_at" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the configuration of a vector index, addressed by its id or name.", "tags": [ "vector-indexes" ] }, "patch": { "operationId": "configure_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "At least one field is required. deletion_protection: enabled|disabled. tags merge into the existing tags and an empty-string value removes a tag; at most 20 after the merge. Naming any other index field answers 400 immutable_field.", "properties": { "deletion_protection": { "type": "string" }, "tags": { "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is active or deleting; metric is cosine, dot, l2 or manhattan (omitted with dimension for an index without dense vectors); score_direction is always higher_is_better; deletion_protection is enabled or disabled; identifier_profile is unicode or ascii; compat_family is documents, records, vectors or none; embedding is always present and null today; created_at is RFC 3339 UTC with milliseconds.", "properties": { "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "deletion_protection": { "type": "string" }, "dimension": { "type": "integer" }, "embedding": { "description": "Generated-embedding configuration; revision may be null. Indexes with generated embeddings cannot be created yet, so this is null in practice.", "properties": { "dimension": { "type": "integer" }, "document_task": { "type": "string" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "model_config_id": { "type": "string" }, "preprocessing_version": { "type": "string" }, "provider": { "type": "string" }, "query_task": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "model_config_id", "provider", "model", "revision", "dimension", "dtype", "metric", "preprocessing_version", "document_task", "query_task" ], "type": "object" }, "identifier_profile": { "type": "string" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "name": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "state": { "type": "string" }, "tags": { "type": "object" }, "text_fields": { "items": { "properties": { "analyzer": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "analyzer" ], "type": "object" }, "type": "array" }, "visibility_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "index_id", "name", "state", "score_direction", "sparse", "text_fields", "visibility_fields", "embedding", "deletion_protection", "tags", "identifier_profile", "compat_family", "created_at" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Updates the deletion protection and tags of a vector index.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/jobs/{job_id}": { "get": { "operationId": "describe_job", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "kind is update_by_filter or delete_by_filter. state is queued, running, succeeded, limit_reached, failed, cancelled, cancelled_by_namespace_delete, fenced or fenced_authorization. error is a fixed, non-specific text per cause. created_at and updated_at are RFC 3339 UTC with milliseconds. Needs read on the job's namespace; an unknown, expired (finished more than 7 days ago) or ungranted job answers 404 job_not_found.", "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "error": { "type": "string" }, "incarnation_id": { "type": "string" }, "job_id": { "type": "string" }, "kind": { "type": "string" }, "namespace_id": { "type": "string" }, "progress": { "description": "updated is present for an update_by_filter job, deleted for a delete_by_filter job.", "properties": { "deleted": { "type": "integer" }, "examined": { "type": "integer" }, "matched": { "type": "integer" }, "updated": { "type": "integer" } }, "required": [ "examined", "matched" ], "type": "object" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "state": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "job_id", "kind", "state", "namespace_id", "incarnation_id", "restore_epoch", "created_at", "updated_at", "progress" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns a filtered update or delete job of a vector index: its state and progress.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/jobs/{job_id}/cancel": { "post": { "operationId": "cancel_job", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "202": { "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancels a filtered update or delete job: no further round runs, and nothing already applied is rolled back.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/namespaces/configure": { "post": { "operationId": "configure_namespace", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "declared_capacity must be sent: an integer 1-9007199254740991 sets it, null removes it, absent answers 400. A value below current usage answers 409. dry_run: true is refused with 400. Naming another namespace field answers 400 immutable_field.", "properties": { "declared_capacity": { "type": "integer" }, "dry_run": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is active or deleting. declared_capacity is always present and is null when undeclared.", "properties": { "declared_capacity": { "type": "integer" }, "dense_ids": { "type": "integer" }, "name": { "type": "string" }, "namespace_id": { "type": "string" }, "pending_new_records": { "type": "integer" }, "pending_records": { "type": "integer" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "record_count": { "type": "integer" }, "sparse_ids": { "type": "integer" }, "state": { "type": "string" } }, "required": [ "name", "namespace_id", "state", "record_count", "pending_records", "pending_new_records", "dense_ids", "sparse_ids", "declared_capacity", "position" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Sets or removes the declared record capacity of a namespace.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/namespaces/create": { "post": { "operationId": "create_namespace", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "__default__ cannot be created (400 namespace_reserved). declared_capacity is 1-9007199254740991.", "properties": { "declared_capacity": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "description": "201 with the namespace object. state is active or deleting. declared_capacity is always present and is null when undeclared.", "properties": { "declared_capacity": { "type": "integer" }, "dense_ids": { "type": "integer" }, "name": { "type": "string" }, "namespace_id": { "type": "string" }, "pending_new_records": { "type": "integer" }, "pending_records": { "type": "integer" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "record_count": { "type": "integer" }, "sparse_ids": { "type": "integer" }, "state": { "type": "string" } }, "required": [ "name", "namespace_id", "state", "record_count", "pending_records", "pending_new_records", "dense_ids", "sparse_ids", "declared_capacity", "position" ], "type": "object" } } }, "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Creates a namespace in a vector index, optionally with a declared record capacity.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/namespaces/delete": { "post": { "operationId": "delete_namespace", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "confirm must equal name (400 otherwise). __default__ cannot be deleted; clear it with a delete-all instead. dry_run: true is refused with 400.", "properties": { "confirm": { "type": "string" }, "dry_run": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "description": "202; state is always deleting and the receipt carries no records.", "properties": { "namespace_id": { "type": "string" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "state": { "type": "string" } }, "required": [ "namespace_id", "state", "receipt" ], "type": "object" } } }, "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes a namespace and erases its records in the background.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/namespaces/describe": { "post": { "operationId": "describe_namespace", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "include_deleting: true needs manage on the index and currently answers 501.", "properties": { "include_deleting": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "state is active or deleting. declared_capacity is always present and is null when undeclared.", "properties": { "declared_capacity": { "type": "integer" }, "dense_ids": { "type": "integer" }, "name": { "type": "string" }, "namespace_id": { "type": "string" }, "pending_new_records": { "type": "integer" }, "pending_records": { "type": "integer" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "record_count": { "type": "integer" }, "sparse_ids": { "type": "integer" }, "state": { "type": "string" } }, "required": [ "name", "namespace_id", "state", "record_count", "pending_records", "pending_new_records", "dense_ids", "sparse_ids", "declared_capacity", "position" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns a namespace of a vector index with its record counts.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/namespaces/list": { "post": { "operationId": "list_namespaces", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "prefix is 1-512 bytes; limit 1-100, default 100. include_deleting: true needs manage on the index and currently answers 501.", "properties": { "cursor": { "type": "string" }, "include_deleting": { "type": "boolean" }, "limit": { "type": "integer" }, "prefix": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "next_cursor is present only when more namespaces may follow.", "properties": { "namespaces": { "items": { "description": "state is active or deleting. declared_capacity is always present and is null when undeclared.", "properties": { "declared_capacity": { "type": "integer" }, "dense_ids": { "type": "integer" }, "name": { "type": "string" }, "namespace_id": { "type": "string" }, "pending_new_records": { "type": "integer" }, "pending_records": { "type": "integer" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "record_count": { "type": "integer" }, "sparse_ids": { "type": "integer" }, "state": { "type": "string" } }, "required": [ "name", "namespace_id", "state", "record_count", "pending_records", "pending_new_records", "dense_ids", "sparse_ids", "declared_capacity", "position" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "namespaces" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the namespaces of a vector index in name order, with record counts and cursor pagination.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/count": { "post": { "operationId": "count", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "filter_expr is the native filter expression and filter the legacy metadata filter; send at most one. An empty filter counts every record. Counts are never approximate: a filtered count over its budget is refused (413/422).", "properties": { "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "namespace": { "type": "string" } }, "required": [ "namespace" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "namespace": { "type": "string" } }, "required": [ "count", "namespace" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Counts the records of a namespace, exactly, optionally matching a metadata filter.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/delete": { "post": { "operationId": "delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Three forms; exactly one of ids, a filter (filter_expr or filter, at most one) or all: true, otherwise 400 exactly_one_selector. By ids: ids holds 1-1,000 distinct ids of at most 1,024 bytes (dry_run: true refused with 400). By filter: an empty filter is refused (400 filter_empty_for_mutation); dry_run: true counts the matches and writes nothing; a filtered job deletes at most 1,000,000 records, then ends limit_reached; on a namespace holding more than 100,000 records it is refused 501 not_implemented (details.reason = delete_by_filter_namespace_too_large, a provisional bound). One running and 100 retained filtered jobs per namespace; beyond either, 429 job_limit_reached (retryable; details.bound, details.limit). A filtered job needs a key of at least 32 bytes (403 key_scope_insufficient). The job is read at GET .../jobs/{job_id} and stopped at POST .../jobs/{job_id}/cancel. Delete-all: all: true with confirm equal to namespace; dry_run: true returns the count without deleting.", "properties": { "all": { "type": "boolean" }, "confirm": { "type": "string" }, "dry_run": { "type": "boolean" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "ids": { "items": { "type": "string" }, "type": "array" }, "namespace": { "type": "string" } }, "required": [ "namespace" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "By ids: {deleted, missing, receipt}. By filter: dry_run: true answers 200 {dry_run: true, matched_records, sample_ids} (at most 100 ids); otherwise 202 {job_id, receipt}, the receipt of the frame that accepted the job (it lists no records). Delete-all: {receipt} (no records listed). Delete-all dry run: {dry_run: true, record_count}.", "properties": { "deleted": { "type": "integer" }, "dry_run": { "type": "boolean" }, "job_id": { "type": "string" }, "matched_records": { "type": "integer" }, "missing": { "type": "integer" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "record_count": { "type": "integer" }, "sample_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "202": { "content": { "application/json": { "schema": { "description": "By ids: {deleted, missing, receipt}. By filter: dry_run: true answers 200 {dry_run: true, matched_records, sample_ids} (at most 100 ids); otherwise 202 {job_id, receipt}, the receipt of the frame that accepted the job (it lists no records). Delete-all: {receipt} (no records listed). Delete-all dry run: {dry_run: true, record_count}.", "properties": { "deleted": { "type": "integer" }, "dry_run": { "type": "boolean" }, "job_id": { "type": "string" }, "matched_records": { "type": "integer" }, "missing": { "type": "integer" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "record_count": { "type": "integer" }, "sample_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes records by id, every record matching a metadata filter (in a background job), or every record of a namespace with all: true.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/fetch": { "post": { "operationId": "fetch", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "ids: 1-1,000 distinct ids. include_metadata defaults to true, the other include_* to false. metadata_fields (at most 64) narrows metadata and cannot be combined with include_metadata: false; text_fields at most 16. include_pending needs manage and currently answers 501.", "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "include_metadata": { "type": "boolean" }, "include_pending": { "type": "boolean" }, "include_sparse": { "type": "boolean" }, "include_values": { "type": "boolean" }, "metadata_fields": { "items": { "type": "string" }, "type": "array" }, "namespace": { "type": "string" }, "text_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "namespace", "ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An id that does not exist is listed in missing. A response over 4 MB is refused with 413 rather than truncated.", "properties": { "missing": { "items": { "type": "string" }, "type": "array" }, "namespace": { "type": "string" }, "receipt_position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "description": "Map keyed by record id; each value is a record object with the fields listed here.", "properties": { "id": { "type": "string" }, "metadata": { "type": "object" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "sparse_values": { "properties": { "indices": { "items": { "type": "integer" }, "type": "array" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text": { "description": "Map from text field name to {content_hash}; the stored text body is not returned.", "properties": { "content_hash": { "type": "string" } }, "required": [ "content_hash" ], "type": "object" }, "updated_at": { "type": "string" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "id", "rev", "revision_token", "updated_at" ], "type": "object" } }, "required": [ "records", "missing", "namespace", "receipt_position" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Fetches up to 1,000 records of a namespace by id.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/fetch-by-filter": { "post": { "operationId": "fetch_by_filter", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Exactly one of filter_expr or filter is required and it must not be empty. limit 1-10,000, default 100. Projection fields as for fetch. consistency: read_committed (default); snapshot is refused with 400.", "properties": { "consistency": { "type": "string" }, "cursor": { "type": "string" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "include_metadata": { "type": "boolean" }, "include_sparse": { "type": "boolean" }, "include_values": { "type": "boolean" }, "limit": { "type": "integer" }, "metadata_fields": { "items": { "type": "string" }, "type": "array" }, "namespace": { "type": "string" }, "text_fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "namespace" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A page may be short, or empty, and still carry next_cursor; only a page that reached the end omits it.", "properties": { "namespace": { "type": "string" }, "next_cursor": { "type": "string" }, "records": { "description": "Map keyed by record id; each value is a record object with the fields listed here.", "properties": { "id": { "type": "string" }, "metadata": { "type": "object" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "sparse_values": { "properties": { "indices": { "items": { "type": "integer" }, "type": "array" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text": { "description": "Map from text field name to {content_hash}; the stored text body is not returned.", "properties": { "content_hash": { "type": "string" } }, "required": [ "content_hash" ], "type": "object" }, "updated_at": { "type": "string" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "id", "rev", "revision_token", "updated_at" ], "type": "object" } }, "required": [ "records", "namespace" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Fetches the records of a namespace that match a metadata filter, one page at a time.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/list-ids": { "post": { "operationId": "list_ids", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "prefix 1-2,048 bytes; limit 1-1,000, default 100. consistency: read_committed (default); snapshot is refused with 400.", "properties": { "consistency": { "type": "string" }, "cursor": { "type": "string" }, "limit": { "type": "integer" }, "namespace": { "type": "string" }, "prefix": { "type": "string" } }, "required": [ "namespace" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A page may be short, or empty, and still carry next_cursor; only a page that reached the end omits it.", "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "ids" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the record ids of a namespace in byte order, optionally under a prefix, one page at a time.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/update": { "post": { "operationId": "update", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Exactly one selector: id, or a filter (filter_expr is the native filter expression, filter the legacy metadata filter; send at most one); otherwise 400 exactly_one_selector. By id: metadata_remove holds 1-1,024 unique keys; an unknown id answers 404 record_not_found; a stale if_revision_token answers 409; dry_run: true is refused with 400. By filter: only metadata_merge and/or metadata_remove; an empty filter is refused (400 filter_empty_for_mutation); dry_run: true counts the matches and writes nothing. A filtered job updates at most 100,000 records, then ends limit_reached. One running and 100 retained filtered jobs per namespace; beyond either, 429 job_limit_reached (retryable; details.bound, details.limit). A filtered job needs a key of at least 32 bytes (403 key_scope_insufficient). The job is read at GET .../jobs/{job_id} and stopped at POST .../jobs/{job_id}/cancel.", "properties": { "dry_run": { "type": "boolean" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "id": { "type": "string" }, "if_revision_token": { "type": "string" }, "metadata_merge": { "type": "object" }, "metadata_remove": { "items": { "type": "string" }, "type": "array" }, "metadata_replace": { "type": "object" }, "namespace": { "type": "string" }, "sparse_values": { "description": "Unique indices in any order, with one value per index.", "properties": { "indices": { "items": { "type": "integer" }, "type": "array" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text_remove": { "items": { "type": "string" }, "type": "array" }, "text_set": { "type": "object" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "namespace" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "By id: 200 {receipt} listing the one updated record. By filter: dry_run: true answers 200 {dry_run: true, matched_records, sample_ids} (at most 100 ids); otherwise 202 {job_id, receipt}, the receipt of the frame that accepted the job (it lists no records).", "properties": { "dry_run": { "type": "boolean" }, "job_id": { "type": "string" }, "matched_records": { "type": "integer" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "sample_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "202": { "content": { "application/json": { "schema": { "description": "By id: 200 {receipt} listing the one updated record. By filter: dry_run: true answers 200 {dry_run: true, matched_records, sample_ids} (at most 100 ids); otherwise 202 {job_id, receipt}, the receipt of the frame that accepted the job (it lists no records).", "properties": { "dry_run": { "type": "boolean" }, "job_id": { "type": "string" }, "matched_records": { "type": "integer" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "sample_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Accepted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Updates one record by id, or, by metadata filter, every matching record in a background job (with a dry run that only counts).", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/records/upsert": { "post": { "operationId": "upsert", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "records: 1-1,000 with distinct ids; any invalid record refuses the whole batch with per-item errors. expected_generation is refused with 400 (use if_revision_token); dry_run: true is refused with 400.", "properties": { "dry_run": { "type": "boolean" }, "expected_generation": { "type": "integer" }, "namespace": { "type": "string" }, "records": { "items": { "description": "id is non-empty and at most 1,024 bytes; text maps a declared text field to its string.", "properties": { "id": { "type": "string" }, "if_revision_token": { "type": "string" }, "metadata": { "type": "object" }, "sparse_values": { "description": "Unique indices in any order, with one value per index.", "properties": { "indices": { "items": { "type": "integer" }, "type": "array" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "indices", "values" ], "type": "object" }, "text": { "type": "object" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "id" ], "type": "object" }, "type": "array" } }, "required": [ "namespace", "records" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Each receipt record carries rev and revision_token; state is searchable, or durable for a content-identical no-op.", "properties": { "namespace_created": { "type": "boolean" }, "receipt": { "description": "Write receipt. durability_scope is local_fsync, sync_replicated or quorum.", "properties": { "durability_scope": { "type": "string" }, "incarnation_id": { "type": "string" }, "index_id": { "type": "string" }, "namespace_id": { "type": "string" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "records": { "items": { "description": "state is one of accepted, durable_pending, durable, searchable, missing, superseded; revision_token is absent after a delete and for missing ids.", "properties": { "id": { "type": "string" }, "rev": { "type": "integer" }, "revision_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" }, "restore_epoch": { "properties": { "counter": { "type": "integer" }, "nonce_prefix": { "type": "string" } }, "required": [ "counter", "nonce_prefix" ], "type": "object" }, "tenant": { "type": "string" } }, "required": [ "tenant", "index_id", "namespace_id", "incarnation_id", "restore_epoch", "position", "durability_scope", "records" ], "type": "object" }, "upserted_count": { "type": "integer" } }, "required": [ "upserted_count", "namespace_created", "receipt" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Inserts or replaces up to 1,000 records in a namespace, creating the namespace if it does not exist.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector-indexes/{index}/stats": { "get": { "operationId": "index_stats", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "At most 1,000 namespaces are listed (truncated: true beyond); total_record_count covers all of them. dimension and metric are omitted for an index without dense vectors.", "properties": { "dimension": { "type": "integer" }, "index_id": { "type": "string" }, "metric": { "type": "string" }, "namespaces": { "items": { "properties": { "dense_ids": { "type": "integer" }, "name": { "type": "string" }, "namespace_id": { "type": "string" }, "pending_new_records": { "type": "integer" }, "pending_records": { "type": "integer" }, "record_count": { "type": "integer" }, "sparse_ids": { "type": "integer" } }, "required": [ "name", "namespace_id", "record_count", "pending_records", "pending_new_records", "dense_ids", "sparse_ids" ], "type": "object" }, "type": "array" }, "position": { "description": "Read/write position: domain is wal, raft or none; value is ':'.", "properties": { "domain": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "value" ], "type": "object" }, "total_record_count": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "index_id", "namespaces", "total_record_count", "position", "truncated" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns per-namespace record counts and totals for a vector index.", "tags": [ "vector-indexes" ] } }, "/v1/tenants/{tenant}/vector/{table}/create-ivf-pq-index": { "post": { "operationId": "create_ivf_pq_index", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "preset: high_recall | compressed. seed defaults to 0. drop_raw_vectors (default false) irreversibly discards the stored raw vectors table-wide, keeping only compressed codes; refused with 400 for the high_recall preset.", "properties": { "drop_raw_vectors": { "type": "boolean" }, "preset": { "type": "string" }, "seed": { "type": "integer" } }, "required": [ "preset" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "keep_raw is the query-path policy (whether exact re-rank runs); raw_vectors_retained says whether raw vectors are still stored.", "properties": { "dim": { "type": "integer" }, "installed": { "type": "boolean" }, "keep_raw": { "type": "boolean" }, "partitions": { "type": "integer" }, "pq_bits": { "type": "integer" }, "pq_m": { "type": "integer" }, "preset": { "type": "string" }, "raw_vectors_retained": { "type": "boolean" }, "trained": { "type": "boolean" }, "training_corpus_size": { "type": "integer" } }, "required": [ "trained", "installed", "preset", "partitions", "pq_m", "pq_bits", "keep_raw", "raw_vectors_retained", "dim", "training_corpus_size" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Builds a compressed IVF-PQ vector index for a table from a named preset, training it on the table's stored vectors.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/delete-bulk": { "post": { "operationId": "vector_delete_bulk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "ids: at most 10,000, each non-empty and at most 1024 bytes; duplicates count once. index: hnsw (default) | ivf | ivf_pq. repair (HNSW only, default false) runs one graph-repair sweep after the batch.", "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "string" }, "repair": { "type": "boolean" } }, "required": [ "ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted_count": { "type": "integer" }, "missing_count": { "type": "integer" } }, "required": [ "deleted_count", "missing_count" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes up to 10,000 vectors from a vector table in one request and reports how many were deleted and how many were not found.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/put": { "post": { "operationId": "vector_put", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "metric: cosine | dot | l2 | manhattan (alias l1), defaulting to the collection's declared distance, else cosine; quantization: none | scalar | binary; index: hnsw (default) | ivf | ivf_pq (IVF needs installed centroids). `embedding` must have `dim` components. Success is 201 with an empty body.", "properties": { "dim": { "type": "integer" }, "embedder": { "type": "string" }, "embedding": { "items": { "type": "number" }, "type": "array" }, "id": { "type": "string" }, "index": { "type": "string" }, "metadata": { "type": "object" }, "metric": { "type": "string" }, "quantization": { "type": "string" } }, "required": [ "dim", "embedding", "id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Stores one dense vector, with optional metadata, in a vector collection.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/put_bulk": { "post": { "operationId": "vector_put_bulk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Envelope object, not a bare array. More than 100,000 vectors is a 413; an empty `vectors` list answers inserted 0. metric / quantization / index take the same values as the single put. `expected_generation` makes the write conditional on the collection's index generation (409 on mismatch).", "properties": { "dim": { "type": "integer" }, "embedder": { "type": "string" }, "expected_generation": { "type": "string" }, "index": { "type": "string" }, "metric": { "type": "string" }, "quantization": { "type": "string" }, "vectors": { "items": { "properties": { "embedding": { "items": { "type": "number" }, "type": "array" }, "id": { "type": "string" }, "metadata": { "type": "object" } }, "required": [ "embedding", "id" ], "type": "object" }, "type": "array" } }, "required": [ "dim", "vectors" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "elapsed_ms": { "type": "integer" }, "inserted": { "type": "integer" } }, "required": [ "elapsed_ms", "inserted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Stores up to 100,000 dense vectors in a vector collection as one atomic batch.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/put_sparse": { "post": { "operationId": "vector_put_sparse", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "`indices` and `values` must be the same length, every index must be below `dim`, and every value finite; indices need not be sorted (duplicates are summed). Success is 201 with an empty body.", "properties": { "dim": { "type": "integer" }, "id": { "type": "string" }, "indices": { "items": { "type": "integer" }, "type": "array" }, "metadata": { "type": "object" }, "values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "dim", "id", "indices", "values" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Stores one sparse vector (indices, values and dimension), with optional metadata, in a vector collection.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/topk": { "post": { "operationId": "vector_topk", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The query vector field is `query` (not `vector`). mode: fast | high_recall (default); index: hnsw (default) | ivf | ivf_pq; nprobe (1-256) applies to ivf / ivf_pq; refine_k_factor (1-64) applies to ivf_pq with raw vectors kept; engine \"bruteforce\" forces an exact scan. k above the server ceiling (default 4096) is a 400. `filter` is a strict-equality metadata map ({field: value}); `filter_expr` is the typed operator filter (e.g. {\"tag\": {\"$eq\": \"a\"}}) and cannot be combined with a non-empty `filter`; `require_complete: true` turns an underfilled filtered answer into a 422.", "properties": { "dim": { "type": "integer" }, "embedder": { "type": "string" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "index": { "type": "string" }, "k": { "type": "integer" }, "metric": { "type": "string" }, "mode": { "type": "string" }, "nprobe": { "type": "integer" }, "query": { "items": { "type": "number" }, "type": "array" }, "refine_k_factor": { "type": "integer" }, "require_complete": { "type": "boolean" } }, "required": [ "dim", "k", "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Best match first. When a filter runs, the x-oc-filter-completeness response header reports whether the answer is complete.", "items": { "properties": { "id": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the k stored vectors nearest to a query vector, optionally filtered by metadata.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/topk_explain": { "post": { "operationId": "vector_topk_explain", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Same body as the vector top-k search. query must be finite numbers of length dim. metric: cosine|dot|l2|manhattan. filter: equality map {field: value} (explicit null is 400). filter_expr: typed filter expression; not combinable with a non-empty filter. require_complete=true turns an underfilled filtered answer into 422. mode: fast | high_recall (default). engine: hnsw | bruteforce (internal tuning knob). index: hnsw (default) | ivf | ivf_pq. nprobe: 1..256 cells for ivf/ivf_pq. refine_k_factor: ivf_pq exact re-rank over-fetch factor.", "properties": { "dim": { "type": "integer" }, "embedder": { "type": "string" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "index": { "type": "string" }, "k": { "type": "integer" }, "metric": { "type": "string" }, "mode": { "type": "string" }, "nprobe": { "type": "integer" }, "query": { "items": { "type": "number" }, "type": "array" }, "refine_k_factor": { "type": "integer" }, "require_complete": { "type": "boolean" } }, "required": [ "query", "k", "dim" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "completeness appears only for a filtered request from an unrestricted caller.", "properties": { "completeness": { "description": "value is exact|exhausted|ann_full|ann_underfilled; reason (beam_cap|exact_scan_row_cap|exact_scan_unscorable_rows|ivf_probe_exhausted|ivf_pq_candidate_cap) and examined appear only for ann_underfilled.", "properties": { "examined": { "type": "integer" }, "reason": { "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "config": { "description": "metric and index are the lowercased internal names: metric is cosine|dot|l2|manhattan; index is hnsw|ivf|ivfpq (note: 'ivfpq' without underscore, unlike the request's 'ivf_pq'). engine names the path that ran: hnsw|bruteforce|exact_scan|ivf|ivf_pq. ef_search/m/beam_width appear only when an HNSW graph was walked; nprobe/ivf_partitions only on IVF/IVF-PQ; refine_k_factor only on an IVF-PQ table that keeps raw vectors.", "properties": { "beam_width": { "type": "integer" }, "dim": { "type": "integer" }, "ef_search": { "type": "integer" }, "engine": { "type": "string" }, "index": { "type": "string" }, "ivf_partitions": { "type": "integer" }, "k": { "type": "integer" }, "m": { "type": "integer" }, "metric": { "type": "string" }, "nprobe": { "type": "integer" }, "refine_k_factor": { "type": "integer" } }, "required": [ "metric", "index", "dim", "k", "engine" ], "type": "object" }, "hits": { "items": { "properties": { "id": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "score" ], "type": "object" }, "type": "array" } }, "required": [ "hits", "config" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs a vector similarity search and returns its hits together with the resolved search configuration.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/topk_hybrid": { "post": { "operationId": "vector_topk_hybrid", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "rrf_k defaults to 60; candidates (per-leg overfetch) defaults to max(4k, 40) and is never below k. dense_mode: fast | high_recall. `filter` is a strict-equality metadata map ({field: value}); `filter_expr` is the typed operator filter (e.g. {\"tag\": {\"$eq\": \"a\"}}) and cannot be combined with a non-empty `filter`; `require_complete: true` turns an underfilled filtered answer into a 422.", "properties": { "candidates": { "type": "integer" }, "dense_dim": { "type": "integer" }, "dense_metric": { "type": "string" }, "dense_mode": { "type": "string" }, "dense_query": { "items": { "type": "number" }, "type": "array" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "k": { "type": "integer" }, "require_complete": { "type": "boolean" }, "rrf_k": { "type": "integer" }, "sparse_dim": { "type": "integer" }, "sparse_query_indices": { "items": { "type": "integer" }, "type": "array" }, "sparse_query_values": { "items": { "type": "number" }, "type": "array" } }, "required": [ "dense_dim", "dense_query", "k", "sparse_dim", "sparse_query_indices", "sparse_query_values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Fused RRF scores, best first; same hit shape as the dense top-k.", "items": { "properties": { "id": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runs a dense and a sparse nearest-neighbour search in one request and returns a single list fused by Reciprocal Rank Fusion.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/topk_sparse": { "post": { "operationId": "vector_topk_sparse", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "`filter` is a strict-equality metadata map ({field: value}); `filter_expr` is the typed operator filter (e.g. {\"tag\": {\"$eq\": \"a\"}}) and cannot be combined with a non-empty `filter`; `require_complete: true` turns an underfilled filtered answer into a 422.", "properties": { "dim": { "type": "integer" }, "filter": { "type": "object" }, "filter_expr": { "type": "object" }, "k": { "type": "integer" }, "query_indices": { "items": { "type": "integer" }, "type": "array" }, "query_values": { "items": { "type": "number" }, "type": "array" }, "require_complete": { "type": "boolean" } }, "required": [ "dim", "k", "query_indices", "query_values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Best match first; same hit shape as the dense top-k.", "items": { "properties": { "id": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "score" ], "type": "object" }, "type": "array" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "408": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "499": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns the k stored sparse vectors most similar to a sparse query vector, optionally filtered by metadata.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vector/{table}/{vec_id}": { "delete": { "operationId": "vector_delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "table", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "vec_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "index", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "repair", "required": false, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "deleted=false means no vector existed under that id and nothing was written. Query index: hnsw (default) | ivf | ivf_pq. repair=true re-links HNSW neighbours across the removed node (ignored for ivf/ivf_pq).", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes one vector from a vector table by id; deleting an id that does not exist still succeeds with deleted set to false.", "tags": [ "vector" ] } }, "/v1/tenants/{tenant}/vectors": { "get": { "operationId": "vectors_list", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Sorted by table name; vector-index record collections are not listed. A list that could not be gathered from every node is refused with 502 rather than returned partial.", "properties": { "complete": { "type": "boolean" }, "tables": { "items": { "properties": { "table": { "type": "string" }, "vectors": { "type": "integer" } }, "required": [ "table", "vectors" ], "type": "object" }, "type": "array" } }, "required": [ "tables", "complete" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lists the tenant's vector tables with their live vector counts.", "tags": [ "vectors" ] } }, "/v1/tenants/{tenant}/watch": { "get": { "operationId": "watch_sse", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "nl", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "schemas", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "poll_ms", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Each default (message) event carries the JSON array of result rows: the initial snapshot, then a fresh snapshot after each change. A snapshot that fails mid-stream is sent as a message event with data {\"error\": ...}; an event named error with data {\"error\": ...} ends the stream. Keep-alive comments are sent while idle. schemas is a comma-separated table list (default: all tables); poll_ms (default 200) is the change-wait interval.", "type": "string" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Streams the live result of a natural-language query as Server-Sent Events, re-sending it whenever the data changes.", "tags": [ "watch" ] } }, "/v1/tenants/{tenant}/webhooks/{hook_id}": { "delete": { "operationId": "webhook_delete", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "hook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "deleted echoes the hook_id that was removed.", "properties": { "deleted": { "type": "string" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deletes a webhook registration, so later deliveries to that hook are refused.", "tags": [ "webhooks" ] }, "get": { "operationId": "webhook_get", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "hook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A hook the caller may not read answers the same 404 as an unregistered hook.", "properties": { "config": { "description": "Same shape as the PUT body. field_mapping maps destination column name -> JSONPath-style expression (string). Unset optional fields are omitted.", "properties": { "array_path": { "type": "string" }, "field_mapping": { "type": "object" }, "idempotency_key_path": { "type": "string" }, "schema": { "type": "string" }, "signature": { "description": "format is one of: hex_sha256, stripe_t1. secret_env_var is the NAME of the setting that holds the shared secret, not the secret.", "properties": { "format": { "type": "string" }, "header": { "type": "string" }, "secret_env_var": { "type": "string" } }, "required": [ "header", "secret_env_var", "format" ], "type": "object" } }, "required": [ "schema", "field_mapping" ], "type": "object" }, "hook_id": { "type": "string" } }, "required": [ "hook_id", "config" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Returns a registered webhook's configuration, including the name of its signing-secret setting but never the secret itself.", "tags": [ "webhooks" ] }, "post": { "operationId": "webhook_receive", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "hook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Arbitrary JSON payload from the sending service (read as raw bytes and parsed as JSON; Content-Type is not checked). With array_path set, the value at that path must be an array (or null = zero rows); otherwise the whole payload is one record. Signature header value: hex_sha256 = hex of HMAC-SHA256(secret, body); stripe_t1 = 't=,v1=' over '.'. A mapped row naming a missing foreign-key parent is refused with 503 + Retry-After: 5 so the sender redelivers.", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "rows_ingested is 0 when the payload mapped to no records.", "properties": { "hook_id": { "type": "string" }, "rows_ingested": { "type": "integer" } }, "required": [ "rows_ingested", "hook_id" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Receives a delivery for a registered webhook: when the hook has a signature block, the request must carry an HMAC-SHA256 signature of the raw body in the configured header (a missing or invalid signature returns 401), the JSON payload is mapped through the hook's field mapping, and the resulting rows are written to the destination table; the request also passes the standard bearer-token check.", "tags": [ "webhooks" ] }, "put": { "operationId": "webhook_put", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "hook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DbUser" }, { "$ref": "#/components/parameters/DbKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "schema is the destination table id (namespace.table) and must already exist. field_mapping maps destination column name -> JSONPath-style expression (e.g. $.event.id, $.items[0].id) and must have at least one entry. Without a signature block the hook accepts unsigned deliveries.", "properties": { "array_path": { "type": "string" }, "field_mapping": { "type": "object" }, "idempotency_key_path": { "type": "string" }, "schema": { "type": "string" }, "signature": { "description": "format is one of: hex_sha256 (default), stripe_t1. secret_env_var is the NAME of a setting on the database server that holds the shared secret; the secret value itself is never sent or returned.", "properties": { "format": { "type": "string" }, "header": { "type": "string" }, "secret_env_var": { "type": "string" } }, "required": [ "header", "secret_env_var" ], "type": "object" } }, "required": [ "schema", "field_mapping" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Echoes the stored configuration; unset optional fields are omitted.", "properties": { "array_path": { "type": "string" }, "field_mapping": { "type": "object" }, "idempotency_key_path": { "type": "string" }, "schema": { "type": "string" }, "signature": { "description": "format is one of: hex_sha256, stripe_t1.", "properties": { "format": { "type": "string" }, "header": { "type": "string" }, "secret_env_var": { "type": "string" } }, "required": [ "header", "secret_env_var", "format" ], "type": "object" } }, "required": [ "schema", "field_mapping" ], "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Registers or replaces a webhook that maps incoming JSON payloads onto rows of an existing table, with optional HMAC signature verification.", "tags": [ "webhooks" ] } }, "/v1/version": { "get": { "operationId": "version", "responses": { "200": { "content": { "application/json": { "schema": { "description": "store_backend is mem or strata; strata_poisoned and disk appear only on a disk-backed engine. Build fields are omitted when the build did not stamp them; licence appears only on a self-hosted engine with a licence configured.", "properties": { "build_tag": { "type": "string" }, "built_at": { "type": "string" }, "disk": { "properties": { "free_bytes": { "type": "integer" }, "total_bytes": { "type": "integer" }, "used_fraction": { "type": "number" } }, "required": [ "free_bytes", "total_bytes", "used_fraction" ], "type": "object" }, "git_sha": { "type": "string" }, "licence": { "description": "posture is licensed, grace or refused.", "properties": { "posture": { "type": "string" } }, "required": [ "posture" ], "type": "object" }, "rust": { "type": "string" }, "store_backend": { "type": "string" }, "strata_poisoned": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "version", "store_backend" ], "type": "object" } } }, "description": "OK" } }, "security": [], "summary": "Returns the engine's version, build stamps and storage health.", "tags": [ "system" ] } } }, "servers": [ { "url": "{baseUrl}", "variables": { "baseUrl": { "default": "https://localhost:8080", "description": "Your database's HTTPS endpoint" } } } ] }