{ "openapi": "3.1.0", "info": { "title": "Omnigraph API", "description": "HTTP API for the Omnigraph graph database", "license": { "name": "MIT", "identifier": "MIT" }, "version": "0.15.1" }, "paths": { "/.well-known/oauth-protected-resource": { "get": { "tags": [ "management" ], "operationId": "oauthProtectedResourceMetadata", "responses": { "200": { "description": "Public OAuth protected resource metadata", "content": { "application/json": { "schema": {} } } }, "404": { "description": "OAuth resource identity is not configured" } } } }, "/.well-known/oauth-protected-resource/{resource_path}": { "get": { "tags": [ "management" ], "summary": "The same metadata at the location the `/mcp` challenge advertises for a\nresource identifier with a path: the well-known prefix followed by that\npath (`/.well-known/oauth-protected-resource/mcp` for `https://host/mcp`).\nEvery other suffix is 404.", "operationId": "oauthProtectedResourceMetadataAtResourcePath", "parameters": [ { "name": "resource_path", "in": "path", "description": "The configured resource identifier's path, without its leading `/`", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public OAuth protected resource metadata", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not the configured resource's path, or OAuth resource identity is not configured" } } } }, "/cluster/deployments": { "get": { "tags": [ "cluster" ], "operationId": "deployment_status", "parameters": [ { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentStatusOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`), for example a cluster control object whose stored text is corrupt: an applied policy payload that does not match its recorded digest, or a state file that is not valid cluster state; restore the object from a trusted copy. Its bytes failing to decode as text answer 500 instead", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while evaluating deployment access, or a storage read of a cluster control object (the state file, its lock or a catalog payload) that fails the same way on every read, such as bytes that are not text (`effects: none`)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Deployment ownership changed during the bounded ledger observation; retry this GET within the caller deadline. Also a storage read of a cluster control object (the state file, its lock or a catalog payload) that failed temporarily or for an unknown reason (`effects: none`; retry); graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "cluster" ], "operationId": "deployment_apply", "parameters": [ { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentRequest" } } }, "required": true }, "responses": { "200": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutput" } } } }, "202": { "description": "Durably accepted; poll the exact receipt until in_progress is false and inspect active", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutput" } } } }, "400": { "description": "; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`), including a cluster control object whose stored text is corrupt: a catalog payload that does not match its recorded digest, or a state file that is not valid cluster state; restore the object from a trusted copy. Its bytes failing to decode as text answer 500 instead", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "415": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled deployment completion (code `outcome_unknown`); reconcile the original deployment identity before submitting another deployment. Also, before any effect, a storage read of a cluster control object (the state file, its lock or a catalog payload) that fails the same way on every read, such as bytes that are not text (`effects: none`)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Nothing changed: before any effect, a storage read of a cluster control object (the state file, its lock or a catalog payload) that failed temporarily or for an unknown reason (`effects: none`; retry); graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/cluster/deployments/{deployment_id}": { "get": { "tags": [ "cluster" ], "operationId": "deployment_lookup", "parameters": [ { "name": "deployment_id", "in": "path", "description": "Original deployment identity", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`), for example a cluster control object whose stored text is corrupt: an applied policy payload that does not match its recorded digest, or a state file that is not valid cluster state; restore the object from a trusted copy. Its bytes failing to decode as text answer 500 instead", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or a storage read of a cluster control object (the state file, its lock or a catalog payload) that fails the same way on every read, such as bytes that are not text (`effects: none`)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Deployment ownership changed during the bounded ledger observation; retry this GET within the caller deadline. Also a storage read of a cluster control object (the state file, its lock or a catalog payload) that failed temporarily or for an unknown reason (`effects: none`; retry); graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/cluster/plan": { "post": { "tags": [ "cluster" ], "operationId": "deployment_plan", "parameters": [ { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRequest" } } }, "required": true }, "responses": { "200": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`), including a cluster control object whose stored text is corrupt: a catalog payload that does not match its recorded digest, or a state file that is not valid cluster state; restore the object from a trusted copy. Its bytes failing to decode as text answer 500 instead", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "415": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while evaluating deployment access or planning, or a storage read of a cluster control object (the state file, its lock or a catalog payload) that fails the same way on every read, such as bytes that are not text (`effects: none`)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Nothing was planned: a storage read of a cluster control object (the state file, its lock or a catalog payload) that failed temporarily or for an unknown reason (`effects: none`; retry); graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs": { "get": { "tags": [ "management" ], "summary": "List every graph currently registered with this server.", "description": "Cedar-gated by the server-level policy via the `graph_list` action\nagainst `Omnigraph::Server::\"root\"`.\n\nOrder: alphabetical by `graph_id` (server-sorted so clients see\ndeterministic output across requests).", "operationId": "listGraphs", "parameters": [ { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of registered graphs", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphListOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/discovery": { "get": { "tags": [ "management" ], "operationId": "discoverGraphs", "parameters": [ { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authenticated minimal graph inventory", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphDiscoveryOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Identity credential required", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/access": { "get": { "tags": [ "access" ], "summary": "What the caller's own credential may do on this graph.", "description": "Evaluates the graph's installed policy for the resolved actor once per\naction, with each action's branch and target branch shaped as the route\nthat performs it shapes them. It needs no graph action itself, reads no\ngraph data, and never checks whether a named branch exists.", "operationId": "access", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "A branch whose actions to report, by name; it need not exist.", "required": false, "schema": { "type": "string" } }, { "name": "target_branch", "in": "query", "description": "With `branch`, the branch `branch_create` would create and\n`branch_merge` would merge into, by name.", "required": false, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The actions the caller's credential may take", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessOutput" } } } }, "400": { "description": "An unknown or repeated parameter, a target branch without a branch, or a branch name that is not canonical; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "The installed policy could not be evaluated (code `internal`)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/blob": { "get": { "tags": [ "blobs" ], "summary": "Deliver one logical node or edge Blob cell.", "description": "Managed content is streamed through the bounded transport. External\ndescriptors redirect without target-store I/O. Authorization and target\nresolution share the exact helper used by `/query`.", "operationId": "blobGet", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Select a logical node or edge cell.", "required": true, "schema": { "$ref": "#/components/schemas/EntityKind" } }, { "name": "type", "in": "query", "description": "Accepted-schema node or edge type name.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Logical entity id within the selected type.", "required": true, "schema": { "type": "string" } }, { "name": "property", "in": "query", "description": "Accepted-schema Blob property name.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch to read. Mutually exclusive with `snapshot`; defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "snapshot", "in": "query", "description": "Immutable graph snapshot id. Mutually exclusive with `branch`.", "required": false, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "Strong entity-tag-list precondition, including `*`, evaluated before If-None-Match and Range.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Range", "in": "header", "description": "One `bytes` range. Malformed, unknown-unit, and multiple ranges are ignored in V1.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "If-None-Match", "in": "header", "description": "Weak entity-tag-list comparison, including `*`, evaluated before Range.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "If-Range", "in": "header", "description": "One strong entity tag. A mismatch causes the complete representation to be served.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete managed Blob", "headers": { "Accept-Ranges": { "schema": { "type": "string" }, "description": "The literal value `bytes` for managed content" }, "Content-Length": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Exact served payload length" }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator for the selected managed Blob" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" }, "description": "Exact resolved graph snapshot" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "OpenAPI-only marker for an unstructured octet-stream response body." } } } }, "206": { "description": "One satisfiable managed byte range", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, "Content-Range": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "OpenAPI-only marker for an unstructured octet-stream response body." } } } }, "302": { "description": "External Blob descriptor; the server does not dereference it", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "The literal value `no-store`" }, "Location": { "schema": { "type": "string" }, "description": "Exact stored absolute URI" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" }, "description": "Exact resolved graph snapshot" } } }, "304": { "description": "If-None-Match matched the managed Blob validator", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Complete managed Blob length, as required for a valid 304 Content-Length" }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid selector, target, or non-Blob property; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Unknown entity or null Blob cell; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "If-Match did not strongly match the selected managed Blob validator; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "416": { "description": "Requested managed byte range is unsatisfiable", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Range": { "schema": { "type": "string" }, "description": "Unsatisfied range in the form `bytes */N`" }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Stored Blob integrity failure (code `internal`) or pre-header delivery refusal, including ranged external descriptors that cannot be redirected", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "put": { "tags": [ "blobs" ], "summary": "Replace one Blob value of an existing node or edge with the request body.", "description": "The cell's old value is never read; the entity's other cells are carried\nunchanged. Authorization of `change` on the branch runs before the body is\nread. Once admitted the write is owned by the server: a disconnect loses\nonly the response, never cancels or replays the write.", "operationId": "blobPut", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Select a logical node or edge cell.", "required": true, "schema": { "$ref": "#/components/schemas/EntityKind" } }, { "name": "type", "in": "query", "description": "Accepted-schema node or edge type name.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Logical id of an existing entity within the selected type.", "required": true, "schema": { "type": "string" } }, { "name": "property", "in": "query", "description": "Accepted-schema Blob property name.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch to write. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "`*` to require a value in the cell, or a list of strong entity tags one of which must equal the cell's current ETag. Weak tags never match. The write evaluates it against the branch head it applies to.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The raw bytes to store: at most 33554432 bytes (32 MiB), inclusive.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "OpenAPI-only marker for an unstructured octet-stream response body." } } }, "required": true }, "responses": { "200": { "description": "The bytes are published in one graph commit", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Strong validator of the stored value; equals `etag` in the body" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlobWriteOutput" } } } }, "400": { "description": "Invalid selector, query parameter, If-Match field or target, a non-Blob property, or a carried external reference the graph's policy denies; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Unknown branch, or no entity with this id; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "The request body did not arrive before the body deadline; request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Write-authority conflict, or the branch's incarnation or accepted schema changed while the write retried", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "If-Match did not hold for the cell; `blob_precondition_failure` names its current validator; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "ETag": { "schema": { "type": "string" }, "description": "The cell's current validator, when it holds a managed value" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "The body exceeds the server's Blob put limit (the process `write_max_bytes`, at most 32 MiB), or the value with the entity's carried Blob payloads exceeds it; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "415": { "description": "Content-Type must be application/octet-stream", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source carried from the entity could not be read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Write admission is closed or an overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "blobs" ], "summary": "Set one nullable Blob value of an existing node or edge to null.", "description": "Clearing a cell that is already null publishes nothing. Like a put, the\nclear is owned by the server once admitted.", "operationId": "blobClear", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Select a logical node or edge cell.", "required": true, "schema": { "$ref": "#/components/schemas/EntityKind" } }, { "name": "type", "in": "query", "description": "Accepted-schema node or edge type name.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Logical id of an existing entity within the selected type.", "required": true, "schema": { "type": "string" } }, { "name": "property", "in": "query", "description": "Accepted-schema Blob property name.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch to write. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "`*` to require a value in the cell, or a list of strong entity tags one of which must equal the cell's current ETag. A null cell satisfies neither form.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The cell is null. `commit` is the clear's publication, or `null` when the cell already was null and nothing was published", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlobWriteOutput" } } } }, "400": { "description": "Invalid selector, query parameter, If-Match field or target, a non-Blob or non-nullable property, or a carried external reference the graph's policy denies; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Unknown branch, or no entity with this id; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Write-authority conflict, or the branch's incarnation or accepted schema changed while the write retried", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "If-Match did not hold for the cell; `blob_precondition_failure` names its current validator; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "ETag": { "schema": { "type": "string" }, "description": "The cell's current validator, when it holds a managed value" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "The entity's carried Blob payloads exceed the write's payload limit", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source carried from the entity could not be read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Write admission is closed or an overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "head": { "tags": [ "blobs" ], "summary": "Return the status and representation headers for one Blob cell.", "description": "This is a distinct handler rather than Axum's automatic GET-to-HEAD\nfallback. It never calls `BlobReader::read_range`; Range and If-Range are\ndeliberately ignored while If-None-Match is still evaluated.", "operationId": "blobStat", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Select a logical node or edge cell.", "required": true, "schema": { "$ref": "#/components/schemas/EntityKind" } }, { "name": "type", "in": "query", "description": "Accepted-schema node or edge type name.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Logical entity id within the selected type.", "required": true, "schema": { "type": "string" } }, { "name": "property", "in": "query", "description": "Accepted-schema Blob property name.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch to read. Mutually exclusive with `snapshot`; defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "snapshot", "in": "query", "description": "Immutable graph snapshot id. Mutually exclusive with `branch`.", "required": false, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "Strong entity-tag-list precondition, including `*`, evaluated before If-None-Match.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "If-None-Match", "in": "header", "description": "Weak entity-tag-list comparison, including `*`. Range and If-Range are ignored for HEAD.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Range", "in": "header", "description": "Accepted but ignored for HEAD; metadata always describes the complete selected Blob.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "If-Range", "in": "header", "description": "Accepted but ignored for HEAD together with Range.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed Blob metadata with no response body", "headers": { "Accept-Ranges": { "schema": { "type": "string" }, "description": "The literal value `bytes`" }, "Content-Length": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Complete managed Blob length" }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator for the selected managed Blob" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" }, "description": "Exact resolved graph snapshot" } } }, "302": { "description": "External Blob descriptor; the server does not dereference it", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "The literal value `no-store`" }, "Location": { "schema": { "type": "string" }, "description": "Exact stored absolute URI" }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" }, "description": "Exact resolved graph snapshot" } } }, "304": { "description": "If-None-Match matched the managed Blob validator", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Complete managed Blob length, as required for a valid 304 Content-Length" }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid selector, target, or non-Blob property; HEAD responses have no body; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "401": { "description": "Unauthorized; HEAD responses have no body; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } } }, "403": { "description": "Forbidden; HEAD responses have no body", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "404": { "description": "Unknown entity or null Blob cell; HEAD responses have no body; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "412": { "description": "If-Match did not strongly match the selected managed Blob validator; HEAD responses have no body; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Accept-Ranges": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Omnigraph-Snapshot-Id": { "schema": { "type": "string" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } } }, "500": { "description": "Stored Blob integrity failure (code `internal`) or pre-header delivery refusal, including ranged external descriptors that cannot be redirected; HEAD responses have no body", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/branches": { "get": { "tags": [ "branches" ], "summary": "List all branches.", "description": "Returns branch names sorted by name in byte order. Read-only. The GQ statement\n`branch list` on `POST /query` runs the same body.\n\n`detailed=true` adds `details`: for each branch the caller may `read`, its\nhead commit, the branch and commit it started from, when it was created,\nand when it last moved. Each listed branch costs a read of its latest\nversion, and of the version it was created from once it has written a\ncommit; no commit history is read.", "operationId": "branchList", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "detailed", "in": "query", "description": "`true` adds `details`: each branch's head, the branch and commit it\nstarted from, when it was created, and when it last moved. Defaults\nto `false`. Reads each listed branch's latest version, and the version\nit was created from once it has written a commit, never its commit\nhistory; the names alone read neither.", "required": false, "schema": { "type": "boolean" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of branches", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchListOutput" } } } }, "400": { "description": "Invalid `detailed`; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "branches" ], "summary": "Create a new branch.", "description": "Forks `name` off of `from` (defaults to `main`) at its head, or starts it\nat the published graph commit `from_commit` with that commit's data and\nhistory. The receipt names the branch forked and the commit the new\nbranch starts at. The new branch shares backing dataset data with its\nparent until it is mutated. Returns 409 if `name` already exists. The GQ\nstatement `branch create` on `POST /mutate` runs the same body.", "operationId": "branchCreate", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Branch created", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCreateOutput" } } } }, "400": { "description": "Bad request, or both `from` and `from_commit`; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "`from` names no branch, or `from_commit` names no commit the actor may branch from; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Branch already exists, or the commit `from_commit` names cannot start a branch; see branch_start_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "410": { "description": "The commit `from_commit` names is no longer retained; see branch_start_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/branches/diff": { "get": { "tags": [ "changes" ], "summary": "What a branch changed since its merge base with a target.", "description": "The merge base is the commit `POST /branches/merge` would classify\nagainst; it and the source head are captured together. Changes the target\nmade after the base do not appear. Paged like `GET /diff`.", "operationId": "branchDiff", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Branch whose changes are reported.", "required": true, "schema": { "type": "string" } }, { "name": "target", "in": "query", "description": "Branch the source is compared against. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Opaque continuation from the preceding page of this response.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum changes per page, 1 to 8192; defaults to 1000. Above 8192\nthe request fails with 413; zero is refused with 400.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 8192, "minimum": 1 } }, { "name": "kind", "in": "query", "description": "Repeatable filter: node | edge.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityKind" } } }, { "name": "type", "in": "query", "description": "Repeatable filter: accepted-schema type name.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "op", "in": "query", "description": "Repeatable filter: insert | update | delete.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOp" } } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "What `source` changed since its merge base with `target`: the net entity changes from the base to the source head", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffOutput" } } } }, "400": { "description": "A missing source, an invalid filter or limit, or a rejected page token; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "403": { "description": "The actor cannot read one of the branches", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "A branch is not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "409": { "description": "The base and the source head cross a schema boundary; see change_diff_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "410": { "description": "Retained history for the base is no longer readable; see change_feed_gap", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "413": { "description": "Requested limit exceeds the public change ceiling", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while reading changes", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required before changes can be read; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/branches/merge": { "post": { "tags": [ "branches" ], "summary": "Merge one branch into another.", "description": "Merges `source` into `target` (defaults to `main`). Outcome is one of\n`already_up_to_date`, `fast_forward`, or `merged`. Returns 409 with the\nlist of conflicts if the merge cannot be completed; the target is left\nunchanged in that case. **Destructive** to `target` on success. `commit`\ncarries this merge's own target publication, including for a fast-forward;\nan already-up-to-date merge returns `commit: null`.\n\nWith `dry_run: true` the merge stops after classification and validation:\nthe response reports the outcome it would have now (`commit: null`,\n`dry_run: true`), a conflict answers the same 409, and nothing is written.\nA dry run is a read of both branches and needs no `branch_merge` grant.\n\nWith `delete_branch: true` the source branch is deleted after a successful\nmerge, under its own `branch_delete` policy check. The merge is durable by\nthen, so a deletion refusal or failure never fails the request; it is\nreported via `branch_deleted: false` + `branch_delete_error_details`.\n\nThe GQ statement `branch merge` on `POST /mutate` runs the same body\n(without the deletion composition) and answers the same 409 on conflict.", "operationId": "branchMerge", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMergeRequest" } } }, "required": true }, "responses": { "200": { "description": "Branches merged", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMergeOutput" } } } }, "400": { "description": "Bad request; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Merge conflict", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Merge entity, byte, or recovery-chain ceiling exceeded before effects; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "A merge could not probe or read an allowed external Blob source", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/branches/merge-base": { "get": { "tags": [ "changes" ], "summary": "The merge base of two branches.", "description": "Reads lineage only, by the rule `POST /branches/merge` uses.", "operationId": "branchMergeBase", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Branch that would be merged.", "required": true, "schema": { "type": "string" } }, { "name": "target", "in": "query", "description": "Branch that would receive the merge. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The commit a merge of `source` into `target` would classify against, with the two heads", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeBaseOutput" } } } }, "400": { "description": "A missing or unknown parameter; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "403": { "description": "The actor cannot read one of the branches", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "A branch is not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while reading lineage", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required before lineage can be read; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/branches/{branch_name}": { "delete": { "tags": [ "branches" ], "summary": "Delete a branch.", "description": "**Irreversible.** Removes the branch pointer; commits remain reachable\nonly if referenced by another branch. Returns 404 if the branch does not\nexist. The GQ statement `branch delete` on `POST /mutate` runs the same\nbody.", "operationId": "branchDelete", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch_name", "in": "path", "description": "Branch name to delete", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch deleted", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchDeleteOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Branch not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/changes": { "get": { "tags": [ "changes" ], "summary": "Poll the change feed of one branch.", "description": "At-least-once: retrying a cursor may replay the complete next commit, so\nconsumers apply blocks idempotently by `graph_commit_id` and persist the\nterminal cursor together with its blocks. The server holds no consumer\nstate. `set=` values are validated and select nothing in this release.", "operationId": "changesPoll", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch whose first-parent history is polled. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Durable cursor from a prior terminal page. Mutually exclusive with\n`start` and `page_token`.", "required": false, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "Explicit start mode: `now` (default) | `beginning` |\n`after:`. Mutually exclusive with `cursor` and `page_token`.", "required": false, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Continuation of one bounded poll (keeps its captured cut). Mutually\nexclusive with `cursor` and `start`.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum changes per page, 1 to 8192; defaults to 1000. Above 8192\nthe request fails with 413; zero is refused with 400.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 8192, "minimum": 1 } }, { "name": "kind", "in": "query", "description": "Repeatable filter: node | edge.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityKind" } } }, { "name": "type", "in": "query", "description": "Repeatable filter: accepted-schema type name.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "op", "in": "query", "description": "Repeatable filter: insert | update | delete.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOp" } } }, { "name": "set", "in": "query", "description": "Repeatable session setting, `name=value` in GQ spelling\n(`set=merge_lineage=off`); only `request`-scope settings are accepted.\nValues are validated as session settings; `engine` does not change\nchange-feed execution.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Change blocks in first-parent order. The durable cursor appears only on a terminal page, advanced only over complete commits; a mid-block page carries only next_page_token", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFeedOutput" } } } }, "400": { "description": "Invalid start/filter combination, or a rejected cursor or page token; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "Branch not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "409": { "description": "The feed crossed an unprovable schema boundary; see change_diff_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "410": { "description": "Feed gap: required history was reclaimed; reset via the baseline handshake", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "413": { "description": "Requested limit exceeds the public change ceiling", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while reading changes", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required before changes can be read; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/changes/baseline": { "post": { "tags": [ "changes" ], "summary": "Capture a change-feed baseline: one exact entity snapshot plus the cursor\nthat resumes the feed immediately after it.", "description": "A baseline is a full data export, so it requires the export action. The\nsnapshot honors the scope's kind and type dimensions; `op` binds only the\nresume cursor's feed scope.", "operationId": "changesBaseline", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeBaselineRequest" } } }, "required": true }, "responses": { "200": { "description": "NDJSON entity snapshot pinned at one captured commit. Every preceding record is one type-keyed entity record (the load/export NDJSON shape); the FINAL record is the ChangeBaselineRecord envelope — an interrupted stream has no terminal record and therefore no usable cursor. Install the snapshot durably before the cursor.", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ChangeBaselineRecord" } } } }, "400": { "description": "Invalid scope; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "Branch not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "413": { "description": "Baseline cut or transport capacity exhausted; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while capturing the baseline", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/commits": { "get": { "tags": [ "commits" ], "summary": "List commits, most recent first.", "description": "`branch` selects which history to list: a named branch returns the history\nreachable from that branch's head (the main commits inherited up to the\nfork plus the branch-authored commits); omitting it returns `main`'s\nhistory. There is no cross-branch listing. Ordering is part of the\ncontract: newest first along the branch's first-parent chain, which is\nfalling generation and falling (graph-manifest version, created-at, commit\nid). Read-only.\n\n`limit` pages the history: each page names the head its listing resolved\n(`head_commit_id`) and continues with `next_page_token`, sent back as\n`page_token` with the same `branch`; later pages answer for that head's\nchain even after the branch moves. A page reads only the history it\nreturns. Without `limit` and `page_token` the whole history is one answer.\nA caller whose `read` does not cover every branch continues only from a\ncommit of `branch`'s history: one the branch still holds or a readable\nbranch published costs nothing more; any other is looked for down the\nbranch's history, which costs what the whole listing costs, and a commit\nthe history does not reach is refused (400).\n\n`listing=unpublished` lists instead the unpublished commits whose recorded\ntarget is `branch` (writes `as commit` awaiting `commit publish`), newest\nfirst; each carries `published: false`. `listing=unattached` lists instead\nthe live unattached snapshots whose recorded target is `branch` (writes\n`as unattached branch`), newest first, each with `kind: \"unattached\"`;\nnon-history listings refuse `limit` and `page_token` (400). The retired\n`unpublished` and `unattached` keys are rejected regardless of value.", "operationId": "commitList", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch whose commits to list. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "listing", "in": "query", "description": "Collection to list: `history` (default), `unpublished` proposals, or\n`unattached` snapshots whose recorded target is `branch`, newest first.", "required": false, "schema": { "oneOf": [ { "$ref": "#/components/schemas/CommitListing" } ], "default": "history" } }, { "name": "limit", "in": "query", "description": "Commits per page of the branch's history, 1 to 1000; defaults to 100\nwhen `page_token` is supplied. The page names the head it resolved\nand a `next_page_token`. Without `limit` and\n`page_token` the whole history is listed. Refused with a `listing` other\nthan `history`; above 1000 the request fails with 413.", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1 } }, { "name": "page_token", "in": "query", "description": "Opaque continuation from the preceding page of this listing, sent with\nthe same `branch`; 100 commits per page unless `limit` is set. Later\npages answer for the head the first page resolved.", "required": false, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of commits", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitListOutput" } } } }, "400": { "description": "Invalid `listing`, a retired `unpublished` or `unattached` selector, paging a non-history listing, a zero `limit`, or a rejected page token; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Branch not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Requested limit exceeds 1000 commits per page", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/commits/{commit_id}": { "get": { "tags": [ "commits" ], "summary": "Get a single commit.", "description": "Returns the commit's graph-manifest version, parent commit(s), and creation\nmetadata. Read-only.", "operationId": "commitShow", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "commit_id", "in": "path", "description": "Commit identifier", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Commit details", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Commit not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] }, "delete": { "tags": [ "commits" ], "summary": "Drop an unpublished commit or an unattached snapshot.", "description": "**Irreversible.** Runs under `commit_drop` on the commit's recorded target\nbranch; a denial answers the 404 an unknown id answers. A published commit\nis never dropped (409). Dropping an unattached snapshot also drops every\nunattached descendant, the root's whole chain included. The GQ statement\n`commit drop \"\"` on `POST /mutate` runs the same body.", "operationId": "commitDrop", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "commit_id", "in": "path", "description": "Unpublished commit or unattached snapshot identifier", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Commit dropped: the requested id and every unattached descendant lost addressability, and a proposal's held merge inputs are released", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Commit not found, or its drop is not permitted; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "The commit is published", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/commits/{commit_id}/changes": { "get": { "tags": [ "changes" ], "summary": "Entity changes one commit made relative to its first parent.", "description": "Read-only, in graph vocabulary with exact before/after images. Bounded:\na large commit continues via the opaque `page_token`. `set=` values are\nvalidated and select nothing in this release.", "operationId": "commitChanges", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "commit_id", "in": "path", "description": "Commit identifier", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Opaque continuation from the preceding page of this response.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum changes per page, 1 to 8192; defaults to 1000. Above 8192\nthe request fails with 413; zero is refused with 400.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 8192, "minimum": 1 } }, { "name": "kind", "in": "query", "description": "Repeatable filter: node | edge.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityKind" } } }, { "name": "type", "in": "query", "description": "Repeatable filter: accepted-schema type name.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "op", "in": "query", "description": "Repeatable filter: insert | update | delete.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOp" } } }, { "name": "set", "in": "query", "description": "Repeatable session setting, `name=value` in GQ spelling\n(`set=merge_lineage=off`); only `request`-scope settings are accepted.\nValues are validated as session settings; `engine` does not change\nchange-feed execution.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entity changes this commit made relative to its first parent, in frozen (kind, type, id, op) order with the cause stated once", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitChangesOutput" } } } }, "400": { "description": "Invalid filter or limit, or a rejected page token; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "Commit not found, or the actor cannot read the commit's branch; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "409": { "description": "Commit cannot be entity-diffed (parentless commit or schema boundary); see change_diff_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "410": { "description": "Required retained history is no longer readable; see change_feed_gap and capture a new baseline", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "413": { "description": "Requested limit exceeds the public change ceiling", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while reading changes", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required before changes can be read; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/commits/{commit_id}/publish": { "post": { "tags": [ "commits" ], "summary": "Publish an unpublished commit onto its recorded target branch.", "description": "The target is the branch the commit recorded when it was written `as\ncommit`, so the request carries no body. Runs under `commit_publish` on\nthat branch; a denial answers the 404 an unknown id answers. An\nunattached snapshot (`as unattached branch`) never publishes: 409 with\ncode `unattached_cannot_publish`, after the same authorization. The GQ\nstatement `commit publish \"\"` on `POST /mutate` runs the same body.", "operationId": "commitPublish", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "commit_id", "in": "path", "description": "Unpublished commit identifier", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The commit as published on its recorded target branch; a published id is answered as it stands", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Commit not found, or its publication is not permitted; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "The target's state moved under the proposal's authority (code `conflict`), or the commit is unattached and cannot publish (code `unattached_cannot_publish`, no durable effect)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "The target head moved past the commit's captured parent; the commit can only be dropped; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/diff": { "get": { "tags": [ "changes" ], "summary": "Net entity changes between two read targets.", "description": "`from` and `to` each name a branch (its head now) or a graph commit\n(published, an unpublished proposal, or an unattached snapshot); a string\nnaming both is refused. The first page resolves both sides to exact\ncommits and names them; a large result continues via the opaque\n`page_token`, and every page answers for those same commits.", "operationId": "diff", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Read target the diff starts from: a branch name (its head now) or a\ngraph commit id. A string naming both is refused.", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Read target the diff ends at, spelled as `from`.", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "description": "Opaque continuation from the preceding page of this response.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum changes per page, 1 to 8192; defaults to 1000. Above 8192\nthe request fails with 413; zero is refused with 400.", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 8192, "minimum": 1 } }, { "name": "kind", "in": "query", "description": "Repeatable filter: node | edge.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityKind" } } }, { "name": "type", "in": "query", "description": "Repeatable filter: accepted-schema type name.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "op", "in": "query", "description": "Repeatable filter: insert | update | delete.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOp" } } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Net entity changes between the two resolved commits, in frozen (kind, type, id, op) order, without a cause", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffOutput" } } } }, "400": { "description": "A missing side, an invalid filter or limit, a side naming both a branch and a commit, or a rejected page token; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "404": { "description": "A side names no branch and no commit, or the actor cannot read the branch it resolves to; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "409": { "description": "The two sides cross a schema boundary; see change_diff_refusal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "410": { "description": "Retained history for an endpoint is no longer readable; see change_feed_gap", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "413": { "description": "Requested limit exceeds the public change ceiling", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) while reading changes", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } }, "503": { "description": "Recovery required before changes can be read; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/export": { "post": { "tags": [ "queries" ], "summary": "Stream the contents of a branch as NDJSON.", "description": "Emits one JSON object per line (`application/x-ndjson`). Filter with\n`type_names` (node/edge type names); an empty list streams the entire branch.\nSuitable for large exports — the response is streamed, not buffered.\nRead-only.", "operationId": "export", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } }, "required": true }, "responses": { "200": { "description": "Exported data as NDJSON", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/x-ndjson": {} } }, "400": { "description": "Bad request; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Branch not found; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Export authority conflict", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Export cut or transport capacity exhausted; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "415": { "description": "Request body must use application/json", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "Recovery required; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/load": { "post": { "tags": [ "mutations" ], "summary": "Compatibility-load NDJSON data through a JSON envelope.", "description": "`data` is NDJSON with one record per line. `mode` controls behavior on\nexisting entities: `merge` upserts by id (default), `append` strictly inserts\nabsent ids, and `overwrite` replaces type data. Branch creation is opt-in by\npresence of `from`: with `from` set, a missing `branch` is created from\nit; without `from`, `branch` must already exist — a missing branch is a\n404, never an implicit fork. **Destructive** when `mode` is `overwrite`\nor when the load produces conflicting writes.", "operationId": "load", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRequest" } } }, "required": true }, "responses": { "200": { "description": "Load results", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestOutput" } } } }, "400": { "description": "Bad request; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Prepared load authority changed before effects", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Load input or external Blob admission exceeds a bounded per-operation entity or byte ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source could not be probed or read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/load/ndjson": { "post": { "tags": [ "mutations" ], "summary": "Load one strict, bounded graph-level NDJSON batch.", "description": "Bearer authentication runs in middleware. This handler completes both\nbranch authorization checks before polling the raw body. A successful\nresponse describes logical schema declarations only and is returned after\nthe ordinary graph commit is visible.", "operationId": "loadNdjson", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Target branch. Defaults to `main`. Without `from`, it must exist.", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Parent branch used to create a missing target branch.", "required": false, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "description": "How existing entities are handled. Defaults to `merge`.", "required": false, "schema": { "$ref": "#/components/schemas/LoadMode" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Strict raw graph-level NDJSON. Each nonblank line is exactly one node envelope {\"type\":\"\",\"id\":\"\",\"data\":{...}} or edge envelope {\"edge\":\"\",\"id\":\"\",\"from\":\"\",\"to\":\"\",\"data\":{...}}. `data` defaults to {} and holds user properties; the optional top-level `id` follows ordinary ID semantics. Legacy-vintage graphs also accept `data.id` as identity when top-level `id` is absent and refuse both placements together. Duplicate, unknown, reserved physical, and noncanonical supplied entity-ID members are refused.", "content": { "application/x-ndjson": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "One committed graph-batch result", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphBatchLoadOutput" } } } }, "400": { "description": "Malformed query or graph batch; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Target branch missing without `from`; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Prepared load authority changed before effects", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Request, load, or external Blob admission exceeds a bounded ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "415": { "description": "Content-Type must be application/x-ndjson", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source could not be probed or read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/mutate": { "post": { "tags": [ "mutations" ], "summary": "Apply a GQ mutation to a branch (canonical mutation endpoint).", "description": "Writes to the named `branch` (defaults to `main`). Mutations are atomic\nper call and produce a new commit. Returns counts of nodes and edges\naffected. **Destructive**: on success the branch is updated; rejected\nmutations may still acquire locks briefly. Returns 409 when the prepared\nwrite authority changes before effects.\n\nConditional callers use `POST /mutate/if-graph-commit`, which requires and\nvalidates `Omnigraph-If-Graph-Commit`. This endpoint rejects that header.\n\nPairs with `POST /query` (read-only).\n\nThe GQ statements `branch create`, `branch delete`, and `branch merge`\n(grammar: `BranchStmt` in `omnigraph-compiler`) are also served\nhere, with no `branch`, `name`, or `params`: each runs the handler body\nof its `/branches` route (same Cedar action, admission check, and errors,\nincluding the 409 of a conflicting merge) and answers a `ChangeOutput`\nwhose `outcome` names the effect. `branch list` and the branch control\nreads (`branch diff`, `branch merge-base`, `branch merge … dry run`) are\nrejected with 400; send them to `POST /query`.", "operationId": "mutate", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Mutation results", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeOutput" } } } }, "400": { "description": "Bad request - also returned when `branch list` or a branch control read (`branch diff`, `branch merge-base`, `branch merge … dry run`) arrives here instead of POST /query, when a request target accompanies a branch statement, when a name or parameters accompany a branch statement, and when a commit precondition accompanies a branch statement; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "`branch delete` of a branch that does not exist, as DELETE /branches/{branch_name} answers; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Write-authority conflict; also `branch create` of a branch that already exists, and a conflicting `branch merge`, whose body carries `merge_conflicts`", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Keyed write exceeds the per-commit entity or byte ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source could not be probed or read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/mutate/if-graph-commit": { "post": { "tags": [ "mutations" ], "summary": "Apply a mutation only while the branch still has the required graph head.", "description": "This explicit conditional route requires `Omnigraph-If-Graph-Commit` and\nvalidates its precondition before mutation effects. `/mutate` rejects the\nprecondition header; conditional callers must use this route.", "operationId": "mutateIfGraphCommit", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-If-Graph-Commit", "in": "header", "description": "Required raw graph-head commit id. The mutation runs only while the branch's effective head still equals it.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Conditional mutation results", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeOutput" } } } }, "400": { "description": "Missing, duplicate, malformed, or invalid request; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Write-authority conflict", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "Graph-commit precondition failed; the write had no effect; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Keyed write exceeds the per-commit entity or byte ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "An allowed external Blob source could not be probed or read", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "An overlapping durable recovery intent must be resolved before retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/operations/optimize": { "post": { "tags": [ "operations" ], "summary": "Submit a recorded optimize run on the graph's main branch.", "operationId": "startOptimize", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartOptimizeRequest" } } }, "required": true }, "responses": { "200": { "description": "The operation is terminal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationOutput" } } } }, "202": { "description": "Durably accepted, or still running; look it up by its id until it is terminal", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationOutput" } } } }, "400": { "description": "A non-canonical operation_id, or a max_gate_hold_ms above this server's ceiling; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`): the same id with a different request (`[operation_request_mismatch]`), an id at or before the eviction mark (`[operation_id_expired]`), an outstanding deployment, four unresolved publications, a record from another ledger (`[operation_record_foreign]`), or a state file or operation record whose stored text is corrupt (`[invalid_state_json]`, `[operation_record_invalid]`; bytes that are not text answer 500)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Another operation is active in the maintenance scope, or that scope's admission gate is held across an acceptance; honor `Retry-After`; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), including a storage read of the cluster state, its lock or the operation record that fails the same way on every read (nothing was accepted), or a record write with no definite answer (code `outcome_unknown`); look the operation up by its id", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "The routes are not enabled, admission is closed, a storage read of the cluster state, its lock or the operation record failed temporarily or for an unknown reason, or the operation record write was refused; nothing was accepted (a refusal naming an earlier request of unknown outcome clears once a read sees the record change, or, for an unconditional write or a create whose record never appeared, when the server restarts); graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/operations/{operation_id}": { "get": { "tags": [ "operations" ], "summary": "Look a recorded operation up by its original id, whatever its kind.", "operationId": "getOperation", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "The id the caller submitted", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The operation's record, or `lookup: unknown`", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`): a record from another ledger at this root, the record changed during resolution, or a state file or operation record whose stored text is corrupt (`[invalid_state_json]`, `[operation_record_invalid]`; bytes that are not text answer 500)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), including a storage read of the cluster state, its lock or the operation record that fails the same way on every read (nothing changed), or a resolution write with no definite answer (code `outcome_unknown`); retry the lookup", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "The routes are not enabled, a storage read of the cluster state, its lock or the operation record failed temporarily or for an unknown reason, or a record write was refused; nothing changed, retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/operations/{operation_id}/cancel": { "post": { "tags": [ "operations" ], "summary": "Ask a recorded operation to stop at its next safe boundary.", "operationId": "cancelOperation", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "The id the caller submitted", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The operation is terminal, unchanged; or `lookup: unknown`", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationOutput" } } } }, "202": { "description": "Cancellation requested; a `publishing` operation is unchanged", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Conflict (code `conflict`): a record from another ledger at this root, the record changed during resolution, or a state file or operation record whose stored text is corrupt (`[invalid_state_json]`, `[operation_record_invalid]`; bytes that are not text answer 500)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), including a storage read of the cluster state, its lock or the operation record that fails the same way on every read (nothing changed), or a resolution write with no definite answer (code `outcome_unknown`); look the operation up by its id", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "The routes are not enabled, a storage read of the cluster state, its lock or the operation record failed temporarily or for an unknown reason, or a record write was refused; nothing changed, retry; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/queries": { "get": { "tags": [ "queries" ], "summary": "List the graph's exposed stored queries as a typed tool catalog.", "description": "Returns every stored query in the `queries:` registry, each\nwith its MCP tool name, read/mutate flag, description/instruction, and\ntyped parameters — enough for a client to register them as tools without\nfetching `.gq` source. Cluster-served graphs have no per-query expose flag,\nso the catalog lists them all. Read-gated; the catalog is graph-wide (branch\nindependent — `read` is authorized against `main`). **Not** Cedar-filtered\nper query yet, so it can list a query whose `invoke_query` the caller\nlacks (a known gap until per-query authorization lands).", "operationId": "queriesList", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored-query catalog (every stored query, with typed params)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueriesCatalogOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/queries/{query_name}": { "post": { "tags": [ "queries" ], "summary": "Invoke a curated, server-side stored query by name.", "description": "The query source comes from the graph's `queries:` registry, not the\nrequest body — callers send only runtime inputs (`params`, `branch`,\n`snapshot`). Gated by the `invoke_query` Cedar action at the boundary;\na stored *mutation* additionally passes the engine's `change` gate\n(double-gated). An actor **without** `invoke_query` cannot tell a denied\nquery from a missing one — both return the same 404, so the catalog\ncan't be probed without the grant. Once `invoke_query` is held, the\ninner `read`/`change` gate may surface a 403 for an existing query the\nactor can't run (the intended double-gate signal).", "operationId": "queryInvoke", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "query_name", "in": "path", "description": "Stored query name (the registry key)", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvokeStoredQueryRequest" } ] } } } }, "responses": { "200": { "description": "Read envelope (ReadOutput) or mutation envelope (ChangeOutput), serialized untagged", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeStoredQueryOutput" } } } }, "400": { "description": "Bad request (param type error; snapshot on a stored mutation); api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden (the inner `change` gate for a stored mutation)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Unknown stored query, or `invoke_query` denied — indistinguishable to a caller without the grant; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Stored mutation write-authority conflict, or a full-text index requires explicit rebuilding (full_text_index_rebuild_required) or has no segment at the snapshot (full_text_index_required); neither is cleared by retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Stored keyed mutation exceeds the per-commit entity or byte ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "A stored mutation could not probe or read an allowed external Blob source", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "A stored mutation is blocked by a durable recovery intent; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/queries/{query_name}/if-graph-commit": { "post": { "tags": [ "queries" ], "summary": "Invoke one stored mutation with a required graph-head precondition.", "description": "A distinct path makes support observable before any mutation runs; older\nservers return 404 instead of ignoring an unknown conditional header.", "operationId": "queryInvokeIfGraphCommit", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "query_name", "in": "path", "description": "Stored mutation name (the registry key)", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-If-Graph-Commit", "in": "header", "description": "Required raw graph-head commit id. The stored mutation runs only while the branch's effective head still equals it.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvokeStoredQueryRequest" } ] } } } }, "responses": { "200": { "description": "Stored conditional mutation result", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeOutput" } } } }, "400": { "description": "Missing, duplicate, malformed, read-only, or invalid invocation; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden (the inner `change` gate)", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "Unknown stored mutation, or `invoke_query` denied; not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "Stored mutation write-authority conflict", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "Stored mutation graph-commit precondition failed; the write had no effect; actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "Stored keyed mutation exceeds the per-commit entity or byte ceiling; payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "A stored mutation could not probe or read an allowed external Blob source", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "Per-actor admission cap exceeded; honor `Retry-After` header; too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`), or unsettled write completion (code `outcome_unknown`); follow the returned disposition before another write", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "A stored mutation is blocked by a durable recovery intent; graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/query": { "post": { "tags": [ "queries" ], "summary": "Execute an inline read query.", "description": "Designed for ad-hoc exploration and AI-agent tool-use: short field\nnames (`query`, `name`) match the CLI `-e` flag and the GQ `query`\nkeyword. Mutations (`insert`/`update`/`delete`) are rejected with 400\n-- use `POST /mutate` for writes. Select a branch or snapshot and obtain\nthe pinned graph-commit token with the response. Cedar authorizes Read for\nread queries and Change for `explain load csv`.\n\nThe GQ statement `branch list` is also served here, with no `branch`,\n`snapshot`, `name`, or `params`: it answers one result per branch (field\n`name`, byte order) under the same `read` check as `GET /branches`. So are\nthe branch control reads, each under its route's checks and errors:\n`branch diff [into ]` and `branch diff to `\n(one result per entity change, fields `kind`, `type`, `id`, `op`,\n`before`, `after`; the compared commits and the continuation token in\n`page`; `after page \"\"` and `limit ` continue and bound it),\n`branch merge-base [into ]` and\n`branch merge [into ] dry run` (one result each).\n`branch create`, `branch delete`, and `branch merge` are rejected with\n400; send them to `POST /mutate`.\n\nThe GQ statement `explain query …` is served here too: the query is not\nrun, and the result describes its v2 logical, physical and available\nDataFusion trees, one result per node (fields `tree`, `depth`, `node`, `detail`), followed by\n`plan` entries for the passes and the document's other fields, under the\nrequest's target and `params`. `explain load csv …` answers the accepted\nload plan the same way (`logical_initial`, `logical`, `physical`, then\n`plan` entries), under the request's `branch` alone. It requires the load's\nChange decision before probing the external source's metadata; it reads\nno payload byte and publishes nothing.", "operationId": "query", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query results", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput" } } } }, "400": { "description": "Bad request - also returned when the query body contains mutations (use POST /mutate, for write queries), when a control write statement (`branch create`, `branch delete`, `branch merge`) arrives here instead of POST /mutate, when a request target accompanies a branch statement, and when a name or parameters accompany a branch statement; api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "408": { "description": "request_timeout when the request body deadline passes before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "409": { "description": "A full-text index requires explicit rebuilding (full_text_index_rebuild_required) or has no segment at the snapshot (full_text_index_required); neither is cleared by retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "413": { "description": "payload_too_large when the request body exceeds its route limit before operation admission", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "424": { "description": "A load explain could not probe an allowed external source", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/schema": { "get": { "tags": [ "schema" ], "summary": "Read the current schema source.", "description": "Returns the project's schema as a single string in `.pg` source form.\nUseful for clients that want to introspect available types and properties\nbefore constructing GQ queries. Read-only.", "operationId": "schemaShow", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current schema source", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/graphs/{graph_id}/snapshot": { "get": { "tags": [ "snapshots" ], "summary": "Read the current snapshot of a branch.", "description": "Returns the graph-manifest version plus per-dataset metadata (path,\npublished dataset version, entity count) for every backing dataset on the\nbranch. Defaults to `main` when `branch` is omitted. Read-only.", "operationId": "snapshot", "parameters": [ { "name": "graph_id", "in": "path", "description": "Graph id to route the request to. The `og_` prefix is reserved for system graphs. `og_catalog` is the built-in, storage-free catalogue: it serves only POST /query and GET /schema with their ordinary response bodies. Its query refuses `branch` and `snapshot`; every other route under /graphs/og_catalog returns 405 `method_not_allowed` before effects.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "query", "description": "Branch whose snapshot to read. Defaults to `main`.", "required": false, "schema": { "type": "string" } }, { "name": "Omnigraph-Http-Api", "in": "header", "description": "exactly one Omnigraph-Http-Api header with value 0.14 is required", "required": true, "schema": { "type": "string", "enum": [ "0.14" ] } }, { "name": "Omnigraph-If-Actor", "in": "header", "description": "The actor the caller expects its credential to resolve to. A mismatch is refused with 412 actor_mismatch before graph lookup or effects; a match changes nothing.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Graph snapshot", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotOutput" } } } }, "400": { "description": "api_contract_mismatch when the required API contract header is missing, duplicated or unsupported", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "401": { "description": "Unauthorized; unauthorized when no bearer credential is presented or the server refuses it", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge (RFC 6750 §3). It carries error=\"invalid_token\" when a presented bearer credential was refused, and resource_metadata naming the OAuth protected-resource metadata when the server has an OIDC resource identity." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "403": { "description": "Forbidden", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "404": { "description": "not_found when no graph `graph_id` is served or the caller may not see it, or when no route serves the path", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "405": { "description": "method_not_allowed when the path is served, but not with this method", "headers": { "Allow": { "schema": { "type": "string" }, "description": "The methods the path serves." }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "412": { "description": "actor_mismatch when Omnigraph-If-Actor names another actor than the credential resolves to", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "429": { "description": "too_many_requests when server observer, ingress or operation admission capacity is exhausted; honor Retry-After", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "500": { "description": "Internal failure (code `internal`) before a successful response", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } }, "503": { "description": "graph_unavailable for a known graph that is not served, or service_unavailable when server operation admission is closed; honor Retry-After, and reconcile any earlier write before retrying", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." }, "Retry-After": { "schema": { "type": "string" }, "description": "Minimum delay before a caller-bounded retry of this refused request; not a scheduled server retry." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorOutput" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/healthz": { "get": { "tags": [ "health" ], "summary": "Liveness probe.", "description": "Returns server status and version. Unauthenticated; safe to call from any\ncaller. Use this to confirm the server is reachable before invoking other\nendpoints.", "operationId": "health", "responses": { "200": { "description": "Server is healthy", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthOutput" } } } } } }, "head": { "tags": [ "health" ], "summary": "Liveness probe.", "description": "Returns server status and version. Unauthenticated; safe to call from any\ncaller. Use this to confirm the server is reachable before invoking other\nendpoints.", "operationId": "health_head", "responses": { "200": { "description": "Server is healthy", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } } } } } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readiness witness (RFC 0049).", "description": "Unauthenticated, and therefore minimal: it reports whether this replica\nis serving or draining, the applied `config_digest` it booted from, the\nledger revision and CAS it read, and registry/ready/loading/blocked counts. Graph\nids stay behind authenticated catalog endpoints. Partial availability is\nready but degraded after loading finishes; loading, no available graph or\nshutdown returns 503. A valid\nempty registry is ready. `/healthz` reports liveness independently.", "operationId": "readiness", "responses": { "200": { "description": "Serving", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessOutput" } } } }, "503": { "description": "Graphs loading, no graph available or stopping", "headers": { "Omnigraph-Http-Api": { "schema": { "type": "string", "enum": [ "0.14" ] }, "description": "Supported OmniGraph HTTP API contract." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessOutput" } } } } } } } }, "components": { "schemas": { "AccessAction": { "type": "string", "description": "A graph action a policy decides, as the access route reports it.", "enum": [ "read", "export", "change", "schema_apply", "branch_create", "branch_delete", "branch_merge", "commit_publish", "commit_drop", "invoke_query", "maintain" ] }, "AccessOutput": { "type": "object", "description": "What the caller's own credential may do on one graph, by the graph's\ninstalled policy. It names actions, never the rules that allow them, and\nsays nothing about any other actor.", "required": [ "graph_id", "graph_wide", "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AccessAction" }, "description": "With `branch`, the actions allowed on it, including `branch_delete`,\n`commit_publish`, `commit_drop` and `schema_apply` with it as their\ntarget. With `target_branch` as well, also `branch_create` and\n`branch_merge` from `branch` into it. Empty without `branch`." }, "actor_id": { "type": [ "string", "null" ], "description": "The actor the credential resolves to. Absent only on a server that runs\nwithout authentication." }, "branch": { "type": [ "string", "null" ], "description": "The branch asked about, when one was." }, "client_id": { "type": [ "string", "null" ], "description": "The OAuth client the credential was issued to, when it is a verified\nOIDC access token. The actor stays the person's principal across\nclients. Opaque text the client chose: render it escaped." }, "graph_id": { "type": "string" }, "graph_wide": { "type": "array", "items": { "$ref": "#/components/schemas/AccessAction" }, "description": "Actions allowed with no branch named: the graph-scoped ones, and the\nbranch-scoped ones a single rule allows on every branch (a rule with no\nbranch scope, `branch_scope: any` or `target_branch_scope: any`).\nRules that cover every branch only together, one for protected\nbranches and one for the rest, allow each named branch but leave the\naction out of this list; read `actions` for a branch." }, "target_branch": { "type": [ "string", "null" ], "description": "The target branch asked about, when one was." } } }, "Applicability": { "type": "string", "description": "Whether a suggested source edit can be applied mechanically.", "enum": [ "machine_applicable", "needs_review" ] }, "BlobPreconditionFailureOutput": { "type": "object", "description": "A Blob write's `If-Match` did not hold for the cell (HTTP 412). The write\nhad no effect. `current_etag` is the cell's validator when it holds a\nmanaged value; it is absent for a null or external value, which no tag\nmatches. Distinct from [`PreconditionFailureOutput`], the graph-commit\nprecondition.", "properties": { "current_etag": { "type": [ "string", "null" ] } } }, "BlobRangeOutput": { "type": "object", "description": "Normalized half-open range details for an unsatisfiable managed Blob read.\n\nHTTP also returns `Content-Range: bytes */N`; these fields let SDKs inspect\nthe failure without parsing either that header or the human-readable text.", "required": [ "start", "end", "length" ], "properties": { "end": { "type": "integer", "format": "int64", "minimum": 0 }, "length": { "type": "integer", "format": "int64", "minimum": 0 }, "start": { "type": "integer", "format": "int64", "minimum": 0 } } }, "BlobSelectorOutput": { "type": "object", "description": "One logical graph Blob cell.", "required": [ "entity", "type", "id", "property" ], "properties": { "entity": { "$ref": "#/components/schemas/EntityKind" }, "id": { "type": "string" }, "property": { "type": "string" }, "type": { "type": "string" } } }, "BlobWriteOutput": { "type": "object", "description": "Receipt of a Blob put or clear.\n\nA put leaves managed bytes, with their `size` and `etag`; a clear leaves\nnull, with neither. The `etag` is the one a read at `commit` reports.", "required": [ "selector", "branch", "kind", "commit" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "branch": { "type": "string", "description": "The branch the write published to." }, "commit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommitOutput", "description": "The write's own publication. Always present on the wire; `null` only\nfor a clear of a cell that was already null, which publishes nothing." } ] }, "etag": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/BlobWriteState" }, "selector": { "$ref": "#/components/schemas/BlobSelectorOutput" }, "size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "BlobWriteState": { "type": "string", "description": "The state a Blob write left its cell in. Separate from\n[`BlobContentKindOutput`]: a write can leave the cell null, a stat never\ndescribes one.", "enum": [ "managed", "null" ] }, "BranchCreateOutput": { "type": "object", "required": [ "uri", "from", "name", "from_commit_id" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "from": { "type": "string" }, "from_commit_id": { "type": "string", "description": "The graph commit the new branch starts at: `from`'s head when the\nbranch was created, or the commit `from_commit` named. For a commit\nstart, `from` is the branch that wrote the commit." }, "name": { "type": "string" }, "uri": { "type": "string" } } }, "BranchCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "from": { "type": [ "string", "null" ], "description": "Parent branch to fork from; the new branch starts at its head.\nMutually exclusive with `from_commit`. Defaults to `main`." }, "from_commit": { "type": [ "string", "null" ], "description": "A published graph commit id to start the new branch at, with that\ncommit's data and history. Mutually exclusive with `from`." }, "name": { "type": "string", "description": "Name of the new branch. Must not already exist." } } }, "BranchDeleteOutput": { "type": "object", "required": [ "uri", "name" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "uri": { "type": "string" } } }, "BranchDetailOutput": { "type": "object", "description": "One live branch as `GET /branches?detailed=true` reports it. `from` and\n`from_commit_id` say where the branch started, as its `POST /branches`\nreceipt did. A branch deleted and created again under the same name is a\nnew lifetime: its start and creation time are the later creation's. The\noptional fields are absent on `main`.", "required": [ "name", "head", "updated_at" ], "properties": { "created_at": { "type": [ "integer", "null" ], "format": "int64", "description": "When the branch was created, as Unix epoch microseconds recorded to\nthe second.", "example": 1714000000000000 }, "from": { "type": [ "string", "null" ], "description": "The branch this one started from, as that branch was named then; it\nmay since have been deleted or recreated." }, "from_commit_id": { "type": [ "string", "null" ], "description": "The commit the branch started at. A later merge does not move it;\n`GET /branches/merge-base` answers where two branches last met." }, "head": { "$ref": "#/components/schemas/CommitOutput", "description": "The commit a read of the branch sees: its newest commit, or the commit\nit started at while it has written none." }, "name": { "type": "string" }, "updated_at": { "type": "integer", "format": "int64", "description": "When the head last moved, as Unix epoch microseconds: the time of the\nbranch's newest commit, or `created_at` while it has written none.", "example": 1714000000000000 } } }, "BranchListOutput": { "type": "object", "required": [ "branches" ], "properties": { "branches": { "type": "array", "items": { "type": "string" }, "description": "Every live branch, sorted by name in byte order." }, "details": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BranchDetailOutput" }, "description": "Present only with `detailed=true`: one entry per branch the caller\nmay `read`, in the order of `branches`. A branch the caller may not\nread is listed in `branches` alone." } } }, "BranchMergeOutcome": { "type": "string", "enum": [ "already_up_to_date", "fast_forward", "merged" ] }, "BranchMergeOutput": { "type": "object", "required": [ "source", "target", "outcome", "commit" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "branch_delete_error_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ErrorOutput", "description": "Why the requested source-branch deletion did not happen. Present iff\n`branch_deleted` is `false`." } ] }, "branch_deleted": { "type": [ "boolean", "null" ], "description": "Result of the requested post-merge source-branch deletion. Absent when\n`delete_branch` was not requested; `true` when the source branch was\ndeleted; `false` when the deletion was refused or failed (the merge\nitself still succeeded — see `branch_delete_error_details`)." }, "commit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommitOutput", "description": "This merge's own publication, including for a fast-forward. Always\npresent on the wire; `null` only when already up to date." } ] }, "dry_run": { "type": "boolean", "description": "`true` for a dry run: `outcome` is what the merge would do now, and\n`commit` is `null` because nothing was written." }, "outcome": { "$ref": "#/components/schemas/BranchMergeOutcome" }, "source": { "type": "string" }, "target": { "type": "string" } } }, "BranchMergeRequest": { "type": "object", "required": [ "source" ], "properties": { "as_commit": { "type": "boolean", "description": "Publish the merge as an unpublished commit (`branch merge … as commit`):\nthe target head is unchanged until `commit publish`. Refused together\nwith `delete_branch`, whose source the proposal still holds." }, "delete_branch": { "type": "boolean", "description": "Delete the source branch after a successful merge. The deletion runs\nunder its own `branch_delete` policy check; a refusal or failure is\nreported via `branch_deleted` / `branch_delete_error_details` on the response\nand never fails the already-landed merge." }, "dry_run": { "type": "boolean", "description": "Run the merge through classification and validation and stop: the\nresponse reports the outcome the merge would have now, a conflict\nfails with the same `409` a merge returns, and nothing is written.\nA read of both branches; refused together with `as_commit` and\n`delete_branch`." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SettingsRequest", "description": "Session settings for this request (the Session settings RFC); see [`SettingsRequest`]." } ] }, "source": { "type": "string", "description": "Source branch whose commits will be merged." }, "target": { "type": [ "string", "null" ], "description": "Target branch that will receive the merge. Defaults to `main`." } } }, "BranchOutcomeOutput": { "oneOf": [ { "type": "object", "description": "`name` was forked off `from` at the commit `from_commit_id`: the\nhead of `from`, or the commit a `from commit \"\"` start named,\nwhich `from` wrote.", "required": [ "from", "name", "from_commit_id", "kind" ], "properties": { "from": { "type": "string" }, "from_commit_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "created" ] }, "name": { "type": "string" } } }, { "type": "object", "description": "`name` was removed.", "required": [ "name", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "deleted" ] }, "name": { "type": "string" } } }, { "type": "object", "description": "`source` was merged into `target`; `merge` is the three-way result,\none of `already_up_to_date`, `fast_forward`, `merged`.", "required": [ "source", "target", "merge", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "merged" ] }, "merge": { "$ref": "#/components/schemas/BranchMergeOutcome" }, "source": { "type": "string" }, "target": { "type": "string" } } }, { "type": "object", "description": "`commit publish`: the receipt's `commit` is the now-published commit.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "published" ] } } }, { "type": "object", "description": "`commit drop`: the unpublished commit `graph_commit_id` is gone.", "required": [ "graph_commit_id", "kind" ], "properties": { "graph_commit_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "dropped" ] } } } ], "description": "The effect of a branch statement sent to `POST /mutate`, tagged by `kind`.\nA merge conflict has no kind: it is the 409 `POST /branches/merge` answers.\nThe statement grammar is `BranchStmt` in `omnigraph-compiler`." }, "BranchStartRefusalOutput": { "type": "object", "description": "A branch create refused at the graph commit `from_commit` named; nothing\nwas created.", "required": [ "reason", "graph_commit_id" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "For `branch_deleted`, the branch that wrote the commit." }, "graph_commit_id": { "type": "string" }, "reason": { "$ref": "#/components/schemas/BranchStartRefusalReason" }, "type_name": { "type": [ "string", "null" ], "description": "For `not_retained`, the graph type whose stored version cleanup reclaimed." } } }, "BranchStartRefusalReason": { "type": "string", "description": "Why a branch could not start at the graph commit `from_commit` named.", "enum": [ "not_retained", "schema_changed", "earlier_storage_format", "branch_deleted", "unpublished_commit", "unattached_snapshot", "unknown" ] }, "ChangeBaselineOutput": { "type": "object", "description": "Terminal payload of a baseline stream: the captured snapshot commit and\nthe cursor that resumes the feed immediately after it.", "required": [ "snapshot_commit_id", "resume_cursor" ], "properties": { "resume_cursor": { "type": "string" }, "snapshot_commit_id": { "type": "string" } } }, "ChangeBaselineRecord": { "type": "object", "description": "Wire envelope of the FINAL baseline stream line: `{\"baseline\": {...}}`,\ndistinguishable from snapshot records (which carry `type`/`edge` keys).\nEmitted exactly once, only after every snapshot record — an interrupted\nstream has no terminal record and therefore no usable cursor.", "required": [ "baseline" ], "properties": { "baseline": { "$ref": "#/components/schemas/ChangeBaselineOutput" } } }, "ChangeBaselineRequest": { "type": "object", "description": "Body for the change baseline handshake.", "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to capture. Defaults to `main`." }, "kind": { "type": "array", "items": { "$ref": "#/components/schemas/EntityKind" }, "description": "Feed scope the resume cursor is bound to. The snapshot honors `kind`\nand `type`; `op` constrains only subsequent polls." }, "op": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeOp" } }, "type": { "type": "array", "items": { "type": "string" } } } }, "ChangeBlockOutput": { "type": "object", "description": "One commit block inside a feed page.", "required": [ "cause", "changes" ], "properties": { "cause": { "$ref": "#/components/schemas/ChangeCauseOutput" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityChangeOutput" } } } }, "ChangeCauseOutput": { "type": "object", "description": "The commit cause of one change block, stated once.", "required": [ "graph_commit_id", "authored_branch", "authored_at" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "authored_at": { "type": "integer", "format": "int64", "description": "Authorship time as Unix epoch microseconds — minted before dataset\neffects and stable across retries; deliberately not labeled a commit or\npublication time.", "example": 1714000000000000 }, "authored_branch": { "type": "string", "description": "The branch the commit originally landed on (not the requested branch)." }, "graph_commit_id": { "type": "string" }, "merged_parent_commit_id": { "type": [ "string", "null" ] }, "parent_commit_id": { "type": [ "string", "null" ] } } }, "ChangeDiffRefusalOutput": { "type": "object", "description": "A well-formed entity-diff request this commit cannot satisfy (HTTP 409).", "required": [ "reason", "graph_commit_id" ], "properties": { "graph_commit_id": { "type": "string" }, "reason": { "$ref": "#/components/schemas/ChangeDiffRefusalReason" }, "type_name": { "type": [ "string", "null" ], "description": "The graph type at the schema boundary, when the reason names one." } } }, "ChangeDiffRefusalReason": { "type": "string", "description": "Why a well-formed entity-diff request was refused (HTTP 409).", "enum": [ "parentless_commit", "schema_boundary", "unknown" ] }, "ChangeEndpointsOutput": { "type": "object", "description": "Edge endpoints as graph references. Endpoints belong to each image, so an\nendpoint-moving update has distinct before and after endpoints.", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "ChangeErrorOutput": { "type": "object", "description": "Error envelope for the read-only change surfaces (`…/changes`,\n`…/changes/baseline`, `…/commits/{commit_id}/changes`): a wire-compatible\nprojection of [`ErrorOutput`] restricted to the graph-vocabulary details\nthose routes can produce after their error projection. The write-path\nconflict shapes (key / published-dataset-version / merge / read-set) are\nstructurally absent because change routes cannot produce them. Servers\nserialize [`ErrorOutput`]; every field a change route can populate appears\nhere with the same name and meaning, and absent optionals are wire-compatible.", "required": [ "error", "code", "disposition" ], "properties": { "change_diff_refusal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeDiffRefusalOutput", "description": "Set with HTTP 409 when a commit entity diff is refused (parentless\ncommit or an unprovable schema boundary)." } ] }, "change_feed_gap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeFeedGapOutput", "description": "Set with HTTP 410 when retained history can no longer reconstruct a\nchange continuation. Recover via the baseline handshake." } ] }, "code": { "$ref": "#/components/schemas/ErrorCode", "description": "The failure's registry code, as on [`ErrorOutput`]." }, "disposition": { "$ref": "#/components/schemas/DispositionOutput", "description": "What the request did and what to do next, as on [`ErrorOutput`]." }, "error": { "type": "string" }, "recovery_required": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RecoveryRequiredOutput", "description": "Set with HTTP 503 when the graph has a durable recovery intent that\nmust be resolved before the requested change read can proceed." } ] }, "resource_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceLimitOutput", "description": "Set when a requested limit exceeds a public ceiling, or a single change\nexceeds the poll's own byte ceiling." } ] } } }, "ChangeFeedGapOutput": { "type": "object", "description": "A change continuation can no longer be reconstructed from retained history\n(HTTP 410), sent with [`ErrorCode::ChangeFeedGap`]. Recovery is the\nbaseline handshake; retrying the same cursor cannot succeed.", "required": [ "first_unreadable_commit_id" ], "properties": { "cursor": { "type": [ "string", "null" ] }, "first_unreadable_commit_id": { "type": "string" } } }, "ChangeFeedOutput": { "type": "object", "description": "One bounded feed poll result.", "required": [ "blocks" ], "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeBlockOutput" } }, "caught_up": { "type": [ "boolean", "null" ], "description": "Present with `cursor` on a terminal page: true when the page reached\nits captured head, false when more complete commits already wait." }, "cursor": { "type": [ "string", "null" ], "description": "Durable caller-owned cursor, advanced only over complete commits and\nreturned only on a terminal page — an interrupted poll never advances\nit." }, "next_page_token": { "type": [ "string", "null" ], "description": "Continue this poll's captured cut. Absent on a terminal page." } } }, "ChangeImageOutput": { "type": "object", "description": "One exact logical entity image, decoded with the commit-era schema.", "required": [ "properties" ], "properties": { "endpoints": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeEndpointsOutput", "description": "Present for edge images only." } ] }, "properties": { "description": "Exact logical property values, user-schema keys verbatim; a null cell\nkeeps its key, an absent key was outside that commit's schema." } } }, "ChangeOp": { "type": "string", "description": "Logical operation of one change. Ordering rank is frozen:\ninsert before update before delete within one entity.", "enum": [ "insert", "update", "delete" ] }, "ChangeOutput": { "type": "object", "required": [ "branch", "query_name", "affected_nodes", "affected_edges", "commit" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "affected_edges": { "type": "integer", "description": "Edges the mutation touched, under the `affected_nodes` rule.", "minimum": 0 }, "affected_nodes": { "type": "integer", "description": "Nodes the mutation touched. Not reported for a branch statement,\nwhich moves refs, not nodes or edges: `0` whenever `outcome` is present.", "minimum": 0 }, "branch": { "type": "string", "description": "The branch that received the effect, or the recorded target of an\nunattached write (a child inherits its base's target whatever the\nrequest named). For a branch statement: the created branch, the\ndeleted branch (gone by the time this is read), or the merge target." }, "commit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommitOutput", "description": "This write's own publication, including for a fast-forward merge.\nAlways present on the wire; `null` for branch creation, deletion, or\nan already-up-to-date merge, which publish no graph content commit." } ] }, "executed": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LoadExecutedOutput", "description": "Present only when the request was a `load csv` statement whose plan\nthe engine ran (`mode overwrite`): what the plan measured." } ] }, "outcome": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BranchOutcomeOutput", "description": "Present only when the request was a branch statement." } ] }, "query_name": { "type": "string", "description": "The declared mutation's name, or a branch statement's two keywords\n(`branch create`, `branch delete`, `branch merge`)." } } }, "ChangeRequest": { "type": "object", "required": [ "query" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Target branch. Defaults to `main`." }, "name": { "type": [ "string", "null" ], "description": "Name of the mutation to run when `query` declares multiple." }, "params": { "description": "JSON object whose keys match the mutation's declared parameters." }, "query": { "type": "string", "description": "GQ mutation source containing `insert`, `update`, or `delete` statements.\nMay declare multiple named mutations; pick one with `name`. May instead\nbe one branch statement (grammar: `BranchStmt` in `omnigraph-compiler`),\nsent with no `name`, `params`, or `branch`.", "example": "query insert_person($name: String, $age: I32) {\n insert Person { name: $name, age: $age }\n}" }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SettingsRequest", "description": "Session settings for this request (the Session settings RFC); see [`SettingsRequest`]." } ] } }, "additionalProperties": false }, "ChangeTypeOutput": { "type": "object", "description": "Graph-scoped type identity. `id` is opaque: it survives a supported rename\nand changes after drop/re-add. It is not a type-name selector or path.", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "CommitChangesOutput": { "type": "object", "description": "One bounded page of the finite commit entity diff.", "required": [ "cause", "changes" ], "properties": { "cause": { "$ref": "#/components/schemas/ChangeCauseOutput" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityChangeOutput" } }, "next_page_token": { "type": [ "string", "null" ], "description": "Continue THIS bounded response. Absent on the final page. Never a feed\ncursor." } } }, "CommitKind": { "type": "string", "description": "`published`: a commit of a branch's lineage. `unpublished`: a proposal\n(`as commit`) awaiting `commit publish`. `unattached`: an unattached\nsnapshot (`as unattached branch`), which never publishes.", "enum": [ "published", "unpublished", "unattached" ] }, "CommitListOutput": { "type": "object", "required": [ "commits" ], "properties": { "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitOutput" } }, "head_commit_id": { "type": [ "string", "null" ], "description": "The head a paged listing's first page resolved; every later page\nanswers for its first-parent chain and repeats it as its page token\ncarries it, unchecked. Present only when the request set `limit` or\n`page_token`." }, "next_page_token": { "type": [ "string", "null" ], "description": "Continue THIS listing below the last commit of the page. Absent on the\nlast page and on an unpaged listing." } } }, "CommitListing": { "type": "string", "description": "Which commit collection to list. Only branch history supports pagination.", "enum": [ "history", "unpublished", "unattached" ] }, "CommitOutput": { "type": "object", "required": [ "graph_commit_id", "graph_manifest_version", "created_at", "kind" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "format": "int64", "description": "Commit creation time as Unix epoch microseconds.", "example": 1714000000000000 }, "graph_branch": { "type": [ "string", "null" ] }, "graph_commit_id": { "type": "string" }, "graph_manifest_version": { "type": "integer", "format": "int64", "minimum": 0 }, "kind": { "$ref": "#/components/schemas/CommitKind", "description": "Which kind of commit this is. Required on the wire; a legacy receipt\nwithout it derives `published` or `unpublished` from `published`." }, "merged_parent_commit_id": { "type": [ "string", "null" ] }, "parent_commit_id": { "type": [ "string", "null" ] }, "published": { "type": "boolean", "description": "`false` for an unpublished commit (a write `as commit`) or an\nunattached snapshot (a write `as unattached branch`): readable by its\nid, invisible to every branch read; only the former publishes.\n`graph_manifest_version` is then the detached version holding it.\nAlways `kind == published`." }, "root_commit_id": { "type": [ "string", "null" ], "description": "The root of an unattached snapshot's chain, the snapshot's own id on\na root; `null` for the other kinds." } } }, "DeploymentOutput": { "type": "object", "required": [ "deployment", "active", "in_progress" ], "properties": { "active": { "type": "boolean" }, "deployment": { "type": "object" }, "in_progress": { "type": "boolean" } } }, "DeploymentRequest": { "type": "object", "required": [ "deployment_id", "deployment" ], "properties": { "deployment": { "type": "object" }, "deployment_id": { "type": "string" } }, "additionalProperties": false }, "DeploymentStatusOutput": { "type": "object", "required": [ "status", "active", "in_progress" ], "properties": { "active": { "type": "boolean" }, "in_progress": { "type": "boolean" }, "status": { "type": "object" } } }, "DiagnosticOutput": { "type": "object", "description": "The diagnostics contract for a refused query (RFC 0047): a stable code\n(`Q…` parse, `T…` typecheck); where the failure is, as a source position\nor as the stage and expression when it is post-parse; what was expected or\nviolated; and one concrete fix, absent when `expected` names the decision.\nRides `ErrorOutput.diagnostic` as an additive detail because\n[`ErrorCode`] is a closed compatibility contract.", "required": [ "code", "expected" ], "properties": { "code": { "type": "string" }, "expected": { "type": "string" }, "expression": { "type": [ "string", "null" ] }, "fix": { "type": [ "string", "null" ] }, "position": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PositionOutput" } ] }, "stage": { "type": [ "string", "null" ] }, "suggestion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestionOutput" } ] } } }, "DiffOutput": { "type": "object", "description": "One bounded page of a graph diff: the net entity changes between two\nresolved commits, in the commit diff's entity shape and order. There is no\ncause: a range has no single author.", "required": [ "from_commit_id", "to_commit_id", "changes" ], "properties": { "base_commit_id": { "type": [ "string", "null" ], "description": "The merge base, present only for a branch diff." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityChangeOutput" } }, "from_commit_id": { "type": "string", "description": "The commit the `from` side resolved to; for a branch diff, the merge\nbase." }, "next_page_token": { "type": [ "string", "null" ], "description": "Continue THIS bounded response; later pages answer for the same two\ncommits. Absent on the final page." }, "to_commit_id": { "type": "string", "description": "The commit the `to` side resolved to; for a branch diff, the source\nhead." } } }, "DispositionAction": { "type": "string", "enum": [ "fix", "refresh", "retry", "recover", "reconcile" ] }, "DispositionEffects": { "type": "string", "enum": [ "none", "partial", "unknown" ] }, "DispositionOutput": { "type": "object", "description": "What a refused or failed request did and what its caller should do next.\nA server states it on every error response, computed where that knowledge\nis; a client that lost the response knows less, and says so.", "required": [ "effects", "action" ], "properties": { "action": { "$ref": "#/components/schemas/DispositionAction" }, "effects": { "$ref": "#/components/schemas/DispositionEffects" } } }, "EntityChangeOutput": { "type": "object", "description": "One entity change. Cause is stated once on the enclosing block, never here.\nAn insert carries only `after`, an update exact `before` and `after`, a\ndelete only `before`.", "required": [ "kind", "type", "id", "op" ], "properties": { "after": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeImageOutput" } ] }, "before": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeImageOutput" } ] }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/EntityKind" }, "op": { "$ref": "#/components/schemas/ChangeOp" }, "type": { "$ref": "#/components/schemas/ChangeTypeOutput" } } }, "EntityKind": { "type": "string", "description": "Logical graph entity namespace.", "enum": [ "node", "edge" ] }, "ErrorCode": { "type": "string", "description": "The registry of error codes. A server sends each code under the HTTP statuses named with it; a code without one never appears in an HTTP response.\n\n- `unauthorized` (401): The request carries no credential the server accepts: a bearer token is missing, unknown or expired. Supply one the server is configured to verify.\n- `forbidden` (403): The credential's actor may not do this: policy denies the action, or the action needs a policy permit the server has not been given.\n- `not_admitted` (403): The OIDC access token is valid, but the server admits no principal for its subject. Signing in again issues a token for the same subject and cannot help; the server's operator must admit the identity.\n- `bad_request` (400): The request is malformed or invalid: a body, query string, path parameter or header that does not decode, a query the compiler refuses (see `diagnostic`), or a value refused before any effect.\n- `api_contract_mismatch` (400): The request lacks exactly one `Omnigraph-Http-Api` header naming the contract this server speaks. Authentication and this check precede graph access and effects.\n- `actor_mismatch` (412): The request's `Omnigraph-If-Actor` header names another actor than its credential resolves to. Nothing ran.\n- `outcome_unknown` (500): A write whose completion the server could not settle: it may or may not have published. Read the target before writing again; never replay the write blindly. An MCP write call that was cancelled or passed its deadline answers it too.\n- `precondition_failed` (412): A request precondition no longer holds: the branch head moved past `Omnigraph-If-Graph-Commit` (see `precondition_failure`), or a Blob's `If-Match` names a value the cell no longer holds (a write's `blob_precondition_failure` names the current one). Nothing was written.\n- `recovery_required` (503): An overlapping durable recovery intent must be resolved first; see `recovery_required`.\n- `external_blob_source` (424): An admitted external Blob source could not be probed or read; see `external_blob_source`.\n- `change_feed_gap` (410): Retained history can no longer reconstruct a change continuation; see `change_feed_gap`. Resume from a new baseline.\n- `not_found` (404): The graph, branch, commit, query, entity or route the request names does not exist, or the caller may not learn that it does.\n- `method_not_allowed` (405): The request path is served, but not with the request's method.\n- `request_timeout` (408): The request body did not arrive before its deadline; nothing was admitted.\n- `conflict` (409): The request conflicts with the graph's current state: a concurrent change, an existing id, a merge conflict, an index that must be built first, or a commit that cannot be diffed. The details say which.\n- `branch_start_refusal` (409, 410): `branch create` could not start the branch at the commit `from_commit` named, and nothing was created; see `branch_start_refusal`, whose `not_retained` reason answers 410.\n- `unattached_cannot_publish` (409): The commit is an unattached snapshot, a kind that never publishes. Distinct from `conflict`, the authority-moved refusal of a publishable proposal.\n- `writer_fenced` (409): The branch's writer epoch refused the write: another process claimed the branch, or the serving process holds no claim on it; see `writer_fenced`. Nothing was written.\n- `payload_too_large` (413): The request body, or the work it asks for, exceeds a bounded limit; `resource_limit` names the limit when it is the operation's. Split or reduce the request.\n- `unsupported_media_type` (415): The request body's content type is not one the route accepts.\n- `range_not_satisfiable` (416): The requested Blob byte range lies outside the value; see `blob_range`.\n- `too_many_requests` (429): Admission capacity is exhausted: an actor's, the server's, or the MCP endpoint's concurrent tool calls. Nothing started; retry after `Retry-After`.\n- `service_unavailable` (503): Operation admission is closed, or a deployment observation raced an owner change. Nothing started; retry after `Retry-After`, reconciling any earlier write first.\n- `graph_unavailable` (503): A known graph is not being served. The request did not start, so it may be retried once the graph is served again.\n- `internal` (500): The server failed. An error before any write took no effect; see the server log.\n- `cancelled` (no HTTP status): MCP only: the client cancelled a read tool call. A cancelled write answers `outcome_unknown`.\n- `deadline_exceeded` (no HTTP status): MCP only: a read tool call passed its deadline. A write that does answers `outcome_unknown`.\n- `result_too_large` (no HTTP status): MCP only: a tool result exceeds the result limit. Narrow the read.", "enum": [ "unauthorized", "forbidden", "not_admitted", "bad_request", "api_contract_mismatch", "actor_mismatch", "outcome_unknown", "precondition_failed", "recovery_required", "external_blob_source", "change_feed_gap", "not_found", "method_not_allowed", "request_timeout", "conflict", "branch_start_refusal", "unattached_cannot_publish", "writer_fenced", "payload_too_large", "unsupported_media_type", "range_not_satisfiable", "too_many_requests", "service_unavailable", "graph_unavailable", "internal", "cancelled", "deadline_exceeded", "result_too_large" ] }, "ErrorOutput": { "type": "object", "required": [ "error", "code", "disposition" ], "properties": { "blob_precondition_failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BlobPreconditionFailureOutput", "description": "Set with HTTP 412 when a Blob write's `If-Match` did not hold for the\ncell. The `ETag` response header repeats `current_etag` when present." } ] }, "blob_range": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BlobRangeOutput", "description": "Set with HTTP 416 for a valid but unsatisfiable managed Blob byte range.\n`start..end` is half-open and `length` is the selected Blob length." } ] }, "branch_start_refusal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BranchStartRefusalOutput", "description": "Set with HTTP 409, or 410 for `not_retained`, when `branch create`\ncannot start a branch at the commit `from_commit` named." } ] }, "change_diff_refusal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeDiffRefusalOutput", "description": "Set with HTTP 409 when a commit entity diff is refused (parentless\ncommit or an unprovable schema boundary)." } ] }, "change_feed_gap": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChangeFeedGapOutput", "description": "Set with HTTP 410 when retained history can no longer reconstruct a\nchange continuation. Recover via the baseline handshake." } ] }, "code": { "$ref": "#/components/schemas/ErrorCode", "description": "The failure's registry code. Servers set it on every error response; it\nis absent only from a body built outside a server." }, "diagnostic": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DiagnosticOutput", "description": "Set for a refused query: the diagnostics contract's code, position or\nstage, expectation and fix. `error` keeps the one-line rendering." } ] }, "disposition": { "$ref": "#/components/schemas/DispositionOutput", "description": "What the request did and what to do next. Servers set it on every error\nresponse; it is absent only from a body built outside a server." }, "error": { "type": "string" }, "external_blob_source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExternalBlobSourceOutput", "description": "Set with HTTP 424 and `external_blob_source` when an external Blob URI\npassed admission policy but its source could not be probed or read." } ] }, "full_text_index_rebuild_required": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FullTextIndexRebuildRequiredOutput", "description": "Set with HTTP 409 when a selected full-text index requires an explicit\nrebuild before search can succeed. Unlike a write-authority conflict,\nthis condition is not cleared by retrying. This additive discriminator\npreserves the closed [`ErrorCode`] contract." } ] }, "full_text_index_required": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FullTextIndexRequiredOutput", "description": "Set with HTTP 409 when a full-text call reads a declared index that\nhas no segment at the query's snapshot. Building the index clears it;\nretrying does not." } ] }, "key_conflict": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeyConflictOutput", "description": "Set when a strict keyed insert found an existing or concurrently\ninserted logical id. The caller may choose a different id; replaying\nthe same strict operation will not convert it into an upsert." } ] }, "merge_conflicts": { "type": "array", "items": { "$ref": "#/components/schemas/MergeConflictOutput" } }, "precondition_failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PreconditionFailureOutput", "description": "Set with HTTP 412 and `precondition_failed` when a mutation's\ngraph-commit precondition failed." } ] }, "published_dataset_version_conflict": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublishedDatasetVersionConflictOutput", "description": "Set when the conflict is a publisher CAS rejection. The caller's\npre-write view named the expected published dataset version, but the\ngraph manifest now publishes the actual version. Refresh and retry." } ] }, "read_set_conflict": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadSetConflictOutput", "description": "Set when a prepared write's logical authority changed before effects." } ] }, "recovery_required": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RecoveryRequiredOutput", "description": "Set when an overlapping durable recovery intent must be resolved before\nretry. Its dataset effects may or may not have started." } ] }, "resource_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceLimitOutput", "description": "Set when the request must be split into smaller graph commits. The\nrejected attempt has no durable effect." } ] }, "writer_fenced": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WriterFencedOutput", "description": "Set with HTTP 409 and `writer_fenced` when the branch's writer epoch\nrefused a publish or a claim. Nothing was written." } ] } } }, "ExportRequest": { "type": "object", "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to export. Defaults to `main`." }, "type_names": { "type": "array", "items": { "type": "string" }, "description": "Restrict the export to these node/edge type names. Empty exports all types." } }, "additionalProperties": false }, "ExternalBlobSourceOutput": { "type": "object", "description": "Structured details for an allowed external Blob source that could not be\nprobed or read, sent with [`ErrorCode::ExternalBlobSource`].", "required": [ "uri", "reason" ], "properties": { "reason": { "type": "string", "description": "Source-side failure diagnosis. Clients should branch on the presence of\n`external_blob_source`, not parse this human-readable text." }, "uri": { "type": "string", "description": "Normalized, credential-free URI spelling (or a redacted placeholder)." } } }, "FullTextIndexRebuildRequiredOutput": { "type": "object", "description": "A selected full-text index cannot safely serve the current analyzer (HTTP 409).\nThis is not a retryable write conflict: an operator must rebuild the live\nbranch's indexes. Historical snapshots stay unchanged; branch old content\nand rebuild that branch to search it.", "required": [ "index", "reason" ], "properties": { "index": { "type": "string" }, "reason": { "type": "string", "description": "Human-readable diagnosis; branch on the enclosing detail's presence,\nnot this text, to distinguish the operator-action-required condition." } } }, "FullTextIndexRequiredOutput": { "type": "object", "description": "A full-text call read a declared full-text index that has no segment at\nthe query's snapshot (HTTP 409), so no segment carries its analyzer. This\nis not a retryable conflict: an operator builds the branch's index\n(`omnigraph index build --branch `). Historical snapshots stay\nunchanged.", "required": [ "index" ], "properties": { "index": { "type": "string", "description": "The index's property as `Type.property`." } } }, "GraphAvailability": { "type": "string", "enum": [ "loading", "ready", "transitioning", "blocked", "stopping" ] }, "GraphAvailabilityAction": { "type": "string", "enum": [ "none", "wait_for_startup", "wait_for_transition", "apply_correction_or_restart", "wait_for_restart" ] }, "GraphBatchDeclarationOutput": { "type": "object", "description": "One logical declaration touched by a graph-batch load.\n\nThis deliberately carries the accepted-schema name, not a backing dataset\nselector, path, or Lance identity.", "required": [ "name", "entities_loaded" ], "properties": { "entities_loaded": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } } }, "GraphBatchLoadOutput": { "type": "object", "description": "Terminal result for the raw graph-level NDJSON load surface.", "required": [ "branch", "branch_created", "mode", "nodes", "edges", "total_entities", "embedding_generation" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "base_branch": { "type": [ "string", "null" ], "description": "Base branch a fork was requested from, even when the target already\nexisted. `null` when the request omitted `from`." }, "branch": { "type": "string" }, "branch_created": { "type": "boolean" }, "commit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommitOutput" } ] }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/GraphBatchDeclarationOutput" }, "description": "Logical edge declarations touched by this batch, sorted by name." }, "embedding_generation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LoadEmbeddingGeneration", "description": "`unsupported` when a loaded node type declares `@embed`, including\nwhen all vectors were supplied; `null` otherwise." } ] }, "mode": { "$ref": "#/components/schemas/LoadMode" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GraphBatchDeclarationOutput" }, "description": "Logical node declarations touched by this batch, sorted by name." }, "total_entities": { "type": "integer", "minimum": 0 } } }, "GraphDiscoveryEntry": { "type": "object", "description": "A graph's existence, without storage, schema, data, or serving metadata.", "required": [ "graph_id", "display_name" ], "properties": { "display_name": { "type": "string", "description": "Currently the graph identifier; no separate display name is configured." }, "graph_id": { "type": "string" } }, "additionalProperties": false }, "GraphDiscoveryOutput": { "type": "object", "description": "Authenticated minimal inventory from `GET /graphs/discovery`.", "required": [ "graphs" ], "properties": { "graphs": { "type": "array", "items": { "$ref": "#/components/schemas/GraphDiscoveryEntry" } } }, "additionalProperties": false }, "GraphInfo": { "type": "object", "description": "One entry in the response from `GET /graphs`. Cluster operators\nconsume this list to discover which graphs the server is currently\nserving. This legacy metadata includes the storage `uri`; identity-only\nexistence discovery uses [`GraphDiscoveryEntry`] instead.", "required": [ "graph_id", "uri", "state", "read_available", "write_available", "action" ], "properties": { "action": { "$ref": "#/components/schemas/GraphAvailabilityAction" }, "failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GraphStartupFailure" } ] }, "graph_id": { "type": "string" }, "read_available": { "type": "boolean", "description": "Runtime availability; actor policy still gates every operation." }, "state": { "$ref": "#/components/schemas/GraphAvailability" }, "uri": { "type": "string" }, "write_available": { "type": "boolean" } } }, "GraphListOutput": { "type": "object", "description": "Response from `GET /graphs`. Lists every graph registered with the\nserver in alphabetical order by `graph_id` (sorted server-side so\nclients get deterministic output across requests).", "required": [ "graphs" ], "properties": { "graphs": { "type": "array", "items": { "$ref": "#/components/schemas/GraphInfo" } } } }, "GraphStartupFailure": { "type": "string", "description": "Bounded startup classification, without storage paths or error text.", "enum": [ "invalid_configuration", "invalid_policy", "invalid_external_blob_policy", "open_failed", "invalid_stored_queries" ] }, "HealthOutput": { "type": "object", "required": [ "status", "version", "internal_schema_version" ], "properties": { "internal_schema_version": { "type": "integer", "format": "int32", "description": "The internal-schema (storage-format) version this binary writes, the\nhighest it serves. Normal open serves every version from the binary's\nlowest supported one up to this one; a graph below that range is\nrefused until it is upgraded offline or rebuilt, and a graph above it\nneeds a newer binary.", "minimum": 0 }, "source_version": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "version": { "type": "string" } } }, "IngestOutput": { "type": "object", "required": [ "uri", "branch", "branch_created", "mode", "nodes", "edges", "total_entities", "embedding_generation" ], "properties": { "actor_id": { "type": [ "string", "null" ] }, "base_branch": { "type": [ "string", "null" ], "description": "Base branch a fork was requested from (the request's `from`), echoed\neven when the branch already existed. `null` when `from` was absent." }, "branch": { "type": "string" }, "branch_created": { "type": "boolean" }, "commit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommitOutput" } ] }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/GraphBatchDeclarationOutput" }, "description": "Logical edge declarations touched by this load, sorted by name." }, "embedding_generation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LoadEmbeddingGeneration", "description": "`unsupported` when a loaded node type declares `@embed`, including\nwhen all vectors were supplied; `null` otherwise." } ] }, "mode": { "$ref": "#/components/schemas/LoadMode" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GraphBatchDeclarationOutput" }, "description": "Logical node declarations touched by this load, sorted by name." }, "total_entities": { "type": "integer", "minimum": 0 }, "uri": { "type": "string" } } }, "IngestRequest": { "type": "object", "required": [ "data" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Target branch. Defaults to `main`. Without `from`, the branch must\nalready exist — a missing branch is a 404, never an implicit fork." }, "data": { "type": "string", "description": "NDJSON payload: one record per line, each shaped\n`{\"type\": \"\", \"data\": {...}}`.", "example": "{\"type\": \"Person\", \"data\": {\"name\": \"Alice\", \"age\": 30}}\n{\"type\": \"Person\", \"data\": {\"name\": \"Bob\", \"age\": 25}}" }, "from": { "type": [ "string", "null" ], "description": "Parent branch used to create `branch` if it does not exist. Branch\ncreation is opt-in by presence of this field; omit it to require an\nexisting branch." }, "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LoadMode", "description": "How existing entities are handled. Defaults to `merge`." } ] } } }, "InvokeStoredQueryOutput": { "oneOf": [ { "$ref": "#/components/schemas/ReadOutput" }, { "$ref": "#/components/schemas/ChangeOutput" } ], "description": "Response for `POST /queries/{name}`: the read envelope for a stored\nread, or the mutation envelope for a stored mutation. Serialized\n**untagged**, so the wire shape is exactly [`ReadOutput`] or\n[`ChangeOutput`] — classification follows the stored query, not a\nwrapper field." }, "InvokeStoredQueryRequest": { "type": "object", "description": "Body for `POST /queries/{name}` — invokes the server-side stored query\nnamed in the path. The query source and name come from the registry,\nnever the body; only the runtime inputs are supplied here.", "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to run against. Defaults to `main`; for a stored mutation the\nwrite targets this branch." }, "expect_mutation": { "type": [ "boolean", "null" ], "description": "The kind the caller expects: `Some(false)` for\n`omnigraph query `, `Some(true)` for `omnigraph mutate `.\nWhen set and it disagrees with the stored query's actual kind, the\nserver rejects the call (400) so the verb asserts the kind. `None`\n(the default) skips the check — preserving older clients and aliases." }, "params": { "description": "JSON object whose keys match the stored query's declared parameters." }, "snapshot": { "type": [ "string", "null" ], "description": "Snapshot id to read from (read queries only — rejected for a stored\nmutation). Mutually exclusive with `branch`." } } }, "KeyConflictOutput": { "type": "object", "description": "A strict insert rejected because `entity_id` already names an entity in the\nselected node or edge type. The refused write changed nothing; an earlier\nstep of the same request, such as the branch a load forks, may already have\npublished, which the error's `disposition` states. Partial or ambiguous\nattempts surface `recovery_required` instead.", "required": [ "entity_kind", "type_name" ], "properties": { "entity_id": { "type": [ "string", "null" ] }, "entity_kind": { "$ref": "#/components/schemas/EntityKind" }, "type_name": { "type": "string" } } }, "LoadEmbeddingGeneration": { "type": "string", "description": "Load capability for a batch touching a node type with declared `@embed`.", "enum": [ "unsupported" ] }, "LoadExecutedOutput": { "type": "object", "description": "What a `load csv` statement's plan measured as it ran, beside the\nstatement's [`ChangeOutput`]: the source partitions and bytes it read, the\ncount its sink staged, and what each operator did. Absent for an append\nor merge load, which the keyed adapters run, and for every other change.", "required": [ "partitions", "rows", "source_bytes", "operators" ], "properties": { "operators": { "type": "array", "items": { "$ref": "#/components/schemas/LoadOperatorExecutedOutput" }, "description": "One entry per node of the executed plan in post-order, the source\nfirst." }, "partitions": { "type": "integer", "format": "int32", "description": "Source partitions the plan read.", "minimum": 0 }, "rows": { "type": "integer", "format": "int64", "description": "Entities the sink staged.", "minimum": 0 }, "source_bytes": { "type": "integer", "format": "int64", "description": "Bytes of the captured source.", "minimum": 0 } } }, "LoadMode": { "type": "string", "description": "Shadow enum for documenting [`LoadMode`] in the OpenAPI schema.", "enum": [ "overwrite", "append", "merge" ] }, "LoadOperatorExecutedOutput": { "type": "object", "description": "What one operator of an executed load plan did.", "required": [ "id", "node", "operator", "rows", "elapsed_compute_ns", "wall_ns" ], "properties": { "elapsed_compute_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds the operator was computing: the polls of its stream and of\nits workers, never the time it waited for its input or for storage.", "minimum": 0 }, "id": { "type": "integer", "format": "int64", "description": "The plan node's `id`, as the explain document numbers it.", "minimum": 0 }, "node": { "type": "string", "description": "The plan node's kind: `CsvSource`, `Validate`, `FragmentWrite`." }, "operator": { "type": "string", "description": "The operator the node built." }, "partitions": { "type": "integer", "format": "int32", "description": "The output partitions the operator ran, each its own stream: a\n`CsvSource`'s parsers, 1 for every other operator.", "minimum": 0 }, "rows": { "type": "integer", "format": "int64", "description": "What the operator emitted; the sink counts what it staged.", "minimum": 0 }, "slices": { "type": "array", "items": { "$ref": "#/components/schemas/LoadSliceExecutedOutput" }, "description": "The slices of the source a `CsvSource` cut and parsed, in slice order;\nabsent for every other operator." }, "wall_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds from the operator's first poll to its end, waits included;\n`0` where no end was recorded.", "minimum": 0 } } }, "LoadSliceExecutedOutput": { "type": "object", "description": "What one slice of a `CsvSource` measured: a byte range of the capture\nparsed whole by one partition.", "required": [ "slice", "partition", "rows", "elapsed_compute_ns", "start_ns", "end_ns" ], "properties": { "elapsed_compute_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds the slice's parse and normalization took.", "minimum": 0 }, "end_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds after the source's first poll at which the slice's last\nbatch was sent.", "minimum": 0 }, "partition": { "type": "integer", "format": "int32", "description": "The partition that claimed the slice; which one varies between runs.", "minimum": 0 }, "read_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds the slice's partition waited for the source's bytes.", "minimum": 0 }, "rows": { "type": "integer", "format": "int64", "description": "The records the slice held.", "minimum": 0 }, "slice": { "type": "integer", "format": "int32", "description": "The slice's position in the source, from 0; a slice's rows are the\nsame on every run.", "minimum": 0 }, "start_ns": { "type": "integer", "format": "int64", "description": "Nanoseconds after the source's first poll at which the slice was\nclaimed.", "minimum": 0 } } }, "MergeBaseOutput": { "type": "object", "description": "The commit a merge of `source` into `target` would classify against, and\nthe two heads it was computed from.", "required": [ "source", "target", "source_commit_id", "target_commit_id", "merge_base" ], "properties": { "merge_base": { "$ref": "#/components/schemas/CommitOutput" }, "source": { "type": "string" }, "source_commit_id": { "type": "string" }, "target": { "type": "string" }, "target_commit_id": { "type": "string" } } }, "MergeConflictKind": { "type": "string", "enum": [ "divergent_insert", "divergent_update", "delete_vs_update", "orphan_edge", "unique_violation", "cardinality_violation", "value_constraint_violation" ] }, "MergeConflictOutput": { "type": "object", "required": [ "entity_kind", "type_name", "kind", "message" ], "properties": { "entity_id": { "type": [ "string", "null" ] }, "entity_kind": { "$ref": "#/components/schemas/EntityKind" }, "kind": { "$ref": "#/components/schemas/MergeConflictKind" }, "message": { "type": "string" }, "type_name": { "type": "string" } } }, "OperationLookup": { "type": "string", "enum": [ "found", "unknown" ] }, "OperationOutput": { "type": "object", "required": [ "lookup", "in_progress" ], "properties": { "in_progress": { "type": "boolean", "description": "Whether this server is running it now." }, "lookup": { "$ref": "#/components/schemas/OperationLookup" }, "operation": { "type": [ "object", "null" ], "description": "The operation's record; absent for an `unknown` lookup." } } }, "ParamDescriptor": { "type": "object", "description": "One declared parameter of a stored query, projected for the catalog.", "required": [ "name", "kind", "nullable" ], "properties": { "item_kind": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ParamKind", "description": "Element kind when `kind == list` (always a scalar — the grammar\nforbids lists of vectors or nested lists)." } ] }, "kind": { "$ref": "#/components/schemas/ParamKind" }, "name": { "type": "string" }, "nullable": { "type": "boolean", "description": "`false` → the caller must supply it; `true` → optional." }, "vector_dim": { "type": [ "integer", "null" ], "format": "int32", "description": "Dimension when `kind == vector`.", "minimum": 0 } } }, "ParamKind": { "type": "string", "description": "The kind of a stored-query parameter, decomposed so a client (e.g. an\nMCP server) can build a typed input schema with a closed `match` and\nnever re-parse omnigraph's type spelling. `bigint`/`date`/`datetime`/\n`blob` are carried as JSON strings on the wire: a 64-bit integer past\n2^53 loses precision as a JSON number, and Date/DateTime are ISO\nstrings, Blob a blob-URI string.", "enum": [ "string", "bool", "int", "bigint", "float", "date", "datetime", "blob", "vector", "list" ] }, "PlanRequest": { "type": "object", "required": [ "deployment" ], "properties": { "deployment": { "type": "object" } }, "additionalProperties": false }, "PositionOutput": { "type": "object", "description": "A source position: 1-based line and column (in characters) and the byte\noffset.", "required": [ "line", "column", "byte" ], "properties": { "byte": { "type": "integer", "format": "int32", "minimum": 0 }, "column": { "type": "integer", "format": "int32", "minimum": 0 }, "line": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PreconditionFailureOutput": { "type": "object", "description": "Structured details for a caller write-precondition failure: HTTP 412, a\nmutation carried `Omnigraph-If-Graph-Commit: `, and the branch\nhead no longer matches that id. The write had no effect; the caller re-reads\nthe branch and decides again. `actual` is `None` on a branch with no commits.", "required": [ "expected" ], "properties": { "actual": { "type": [ "string", "null" ] }, "expected": { "type": "string" } } }, "PublishedDatasetVersionConflictOutput": { "type": "object", "description": "Structured details for a publisher-level OCC failure. Surfaces alongside\nHTTP 409 when a write was rejected because the caller's pre-write view of\none backing dataset's published version was stale relative to the current\nhead. The expected/actual fields tell the client which dataset to refresh.", "required": [ "entity_kind", "type_name", "expected_published_dataset_version", "actual_published_dataset_version" ], "properties": { "actual_published_dataset_version": { "type": "integer", "format": "int64", "minimum": 0 }, "entity_kind": { "$ref": "#/components/schemas/EntityKind" }, "expected_published_dataset_version": { "type": "integer", "format": "int64", "minimum": 0 }, "type_name": { "type": "string" } } }, "QueriesCatalogOutput": { "type": "object", "description": "Response for `GET /queries`: every stored query in a graph's\nregistry, each with typed parameters.", "required": [ "queries" ], "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/QueryCatalogEntry" } } } }, "QueryCatalogEntry": { "type": "object", "description": "One entry in the stored-query catalog (`GET /queries`).", "required": [ "name", "tool_name", "mutation", "params" ], "properties": { "description": { "type": [ "string", "null" ] }, "instruction": { "type": [ "string", "null" ] }, "mutation": { "type": "boolean", "description": "`true` for a stored mutation → an MCP read-only hint of `false`." }, "name": { "type": "string", "description": "Registry key / invoke path segment (`POST /queries/{name}`)." }, "params": { "type": "array", "items": { "$ref": "#/components/schemas/ParamDescriptor" } }, "tool_name": { "type": "string", "description": "MCP tool id (the `tool_name` override, else `name`)." } } }, "QueryRequest": { "type": "object", "description": "Inline read-query request for `POST /query`.\n\nMutations are rejected with 400 — use `POST /mutate` for write queries.\nField names are deliberately short (`query`, `name`) to match the GQ\nkeyword and the CLI `-e` flag.", "required": [ "query" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Branch to read from. Mutually exclusive with `snapshot`. Defaults to `main`." }, "name": { "type": [ "string", "null" ], "description": "Name of the query to run when `query` declares multiple. Optional when\nonly one query is declared." }, "params": { "description": "JSON object whose keys match the query's declared parameters." }, "query": { "type": "string", "description": "GQ read-query source. May declare one or more named queries; pick one\nwith `name` when more than one is declared. Mutations\n(`insert`/`update`/`delete`) get 400 — use `POST /mutate` instead. May be the branch\nstatement `branch list` or a branch control read (`branch diff …`,\n`branch merge-base …`, `branch merge … dry run`), sent with no `name`,\n`params`, `branch`, or `snapshot`; or one `explain` statement (`explain query …`), which\nanswers the v2 plan instead of\nrunning it, as one result per plan node (fields `tree`, `depth`, `node`,\n`detail`: the logical, physical and available DataFusion trees, then `plan` entries for\nthe passes and the document's other fields), under the same `params`,\n`branch`, or `snapshot` as the query itself. `explain load csv …` answers the accepted\nload plan as the same results (`logical_initial`, `logical`, `physical`, then `plan`\nentries), under `branch` alone: `snapshot`, `name` and `params` are refused.\nIt requires the load's `change` permission before probing source metadata,\nreads no payload byte, and publishes nothing.", "example": "query get_person($name: String) {\n match {\n $p: Person { name: $name }\n }\n return { $p.name, $p.age }\n}" }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SettingsRequest", "description": "Session settings for this request (the Session settings RFC); see [`SettingsRequest`]." } ] }, "snapshot": { "type": [ "string", "null" ], "description": "Snapshot id to read from. Mutually exclusive with `branch`." } }, "additionalProperties": false }, "RankOrder": { "type": "string", "description": "The direction a ranking's score orders rows.", "enum": [ "ascending", "descending" ] }, "RankingOutput": { "type": "object", "description": "The ranking a read ordered its rows by.", "required": [ "by", "order", "exhaustive", "score_columns" ], "properties": { "by": { "$ref": "#/components/schemas/SearchFunction", "description": "The search function the leading `order` key names." }, "exhaustive": { "type": "boolean", "description": "Whether no row the search admitted and did not return outranks a\nreturned one. `bm25` scores every match, so it is always exhaustive.\n`nearest` is exhaustive when the run searched every partition of the\nvector index, scored every row flat or returned every row it\nadmitted, and `false` when a probe cap left partitions unsearched, so\na nearer row may exist. `rrf` is exhaustive when its `nearest` arms\nare." }, "order": { "$ref": "#/components/schemas/RankOrder", "description": "`ascending` for a `nearest` distance (smaller is nearer),\n`descending` for a `bm25` or `rrf` score (larger is more relevant)." }, "score_columns": { "type": "array", "items": { "type": "string" }, "description": "The returned columns that hold the ranking's own score, in return\norder; empty when the read returns none. A column computed from the\nscore is not one." } } }, "ReadOutput": { "type": "object", "required": [ "query_name", "target", "row_count", "rows" ], "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "graph_commit_id": { "type": [ "string", "null" ], "description": "Effective graph head commit id of the exact snapshot this read was\nserved from. On a fresh named branch this is the inherited source head,\nso it is immediately usable as `Omnigraph-If-Graph-Commit` (CLI:\n`--if-commit`) for the branch's first conditional write. The id and rows\ncome from one pinned version, so no separate id fetch is needed." }, "page": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReadPageOutput", "description": "Page state of a paged control read (`branch diff`); absent for every\nother answer." } ] }, "query_name": { "type": "string" }, "ranking": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RankingOutput", "description": "How the read ordered its rows when its order is a search: the\nsearch function, the direction its score ranks, whether the run's\nsearch was exhaustive, and the returned columns holding the score.\nAbsent when the order is no search." } ] }, "row_count": { "type": "integer", "minimum": 0 }, "rows": {}, "target": { "$ref": "#/components/schemas/ReadTargetOutput" } } }, "ReadPageOutput": { "type": "object", "description": "The page state a `branch diff` answer carries: the exact commits it\ncompares, and the token `after page \"\"` continues it with, absent\non its last page.", "properties": { "base_commit_id": { "type": [ "string", "null" ], "description": "The merge base, for a branch's diff since it." }, "from_commit_id": { "type": [ "string", "null" ] }, "next_page_token": { "type": [ "string", "null" ] }, "to_commit_id": { "type": [ "string", "null" ] } } }, "ReadSetConflictOutput": { "type": "object", "description": "Structured authority mismatch for a prepared write. Values are\nstrings because members include optional graph commit ids and future\nauthority tokens, not only numeric published dataset versions.", "required": [ "member" ], "properties": { "actual": { "type": [ "string", "null" ] }, "expected": { "type": [ "string", "null" ] }, "member": { "type": "string" } } }, "ReadTargetOutput": { "type": "object", "properties": { "branch": { "type": [ "string", "null" ] }, "snapshot": { "type": [ "string", "null" ] } } }, "ReadinessOutput": { "type": "object", "description": "The readiness witness of one replica (`GET /readyz`, RFC 0049): whether\nit is serving or draining, the applied revision it booted from, and how\nmany graphs it does and does not serve. Unauthenticated, so it carries\nno graph id: those stay behind `GET /graphs`.", "required": [ "ready", "status", "state_revision", "served_graph_count", "ready_graph_count", "loading_graph_count", "blocked_graph_count", "shutdown_grace_seconds" ], "properties": { "blocked_graph_count": { "type": "integer", "description": "Unavailable graphs outside startup, including closed transitions.", "minimum": 0 }, "booted_serving_digest": { "type": [ "string", "null" ], "description": "The `config_digest` of the applied revision this process booted from.\nFixed for the life of the process: the server never reloads." }, "loading_graph_count": { "type": "integer", "description": "Registered graphs waiting for their initial startup admission.", "minimum": 0 }, "ready": { "type": "boolean", "description": "False during shutdown or when a nonempty inventory has no ready graph." }, "ready_graph_count": { "type": "integer", "description": "Registered graphs whose startup completed successfully.", "minimum": 0 }, "served_graph_count": { "type": "integer", "description": "Number of registered graphs, including blocked entries.", "minimum": 0 }, "shutdown_grace_seconds": { "type": "integer", "format": "int64", "description": "The bound on graceful shutdown, after which the process exits 2.", "minimum": 0 }, "state_cas": { "type": [ "string", "null" ], "description": "The ledger CAS (`sha256:`) the process booted from." }, "state_revision": { "type": "integer", "format": "int64", "description": "The ledger revision the process booted from.", "minimum": 0 }, "status": { "type": "string", "description": "`loading`, `serving`, `degraded`, `blocked` or `draining`." } } }, "RecoveryRequiredOutput": { "type": "object", "required": [ "operation_id" ], "properties": { "operation_id": { "type": "string" } } }, "ResourceLimitOutput": { "type": "object", "description": "A write rejected before durable recovery ownership because its bounded\nphysical plan exceeded an explicit entity, byte, or transaction-chain ceiling.", "required": [ "resource", "limit", "actual" ], "properties": { "actual": { "type": "integer", "format": "int64", "minimum": 0 }, "limit": { "type": "integer", "format": "int64", "minimum": 0 }, "resource": { "type": "string" } } }, "SchemaOutput": { "type": "object", "required": [ "schema_source" ], "properties": { "catalogue_source": { "type": [ "string", "null" ], "description": "The engine catalogue's built-in `@` types as `.pg`-style\ndeclarations, listed beside the graph's own schema: read-only rows\nthe binary derives from its registries, never part of the schema\nsource above. Optional for compatibility with servers predating it." }, "schema_source": { "type": "string" }, "system_columns": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SystemColumnsOutput", "description": "The graph's physical system column spellings: `__id`/`__src`/`__dst`\non current-vintage graphs, `id`/`src`/`dst` on legacy ones. This is\nstorage discovery for loaders, exports and raw readers of mixed\nvintages; query results address identity and endpoints through the\nmeta-fields `@id`, `@src` and `@dst` on every vintage. Optional for\ncompatibility with servers predating the field." } ] } } }, "SearchFunction": { "type": "string", "description": "The search function a ranked read orders by.", "enum": [ "nearest", "bm25", "rrf" ] }, "SettingsRequest": { "type": "object", "description": "The `settings` field of a request: one optional value per `request`-scope\nsetting of the definition, applied to the request's session before the\nsource's own `set` lines, so a `set` line in the request's text overrides\nthe field. An absent field is empty. A `process` setting has no field\nhere, so `{\"stage_write_concurrency\": 64}` is refused as an unknown field.", "properties": { "ann_nprobes": { "type": "integer", "description": "the partition cap per index delta of a `nearest` scan; `0` is no cap", "minimum": 0 }, "change_lineage": { "type": "string", "description": "how a graph diff or commit page finds the entities it compares across a window with no adjacent transaction: the exact ordered merge of both versions, the entities paired by stable identity, or both compared", "enum": [ "off", "on", "verify" ] }, "engine": { "type": "string", "description": "the engine a read query runs on; `v2`, the plan runner, is the one value; this setting does not change change-feed or merge execution", "enum": [ "v2" ] }, "history_release_bytes": { "type": "integer", "description": "the byte budget of a branch's buffer of unreleased commits; a mutate, load or branch merge of this session whose buffer and head reach it closes a history block and the publish after it writes the block under `__history`; query results never change, only where settled commits are stored and how many requests a publish makes", "maximum": 262144, "minimum": 1024 }, "load_source_max_bytes": { "type": "integer", "description": "the largest object a `load csv` statement reads, checked before any payload byte is fetched; a served load is additionally bounded by the server's workload admission", "minimum": 1 }, "merge_lineage": { "type": "string", "description": "how a merge finds the entities it classifies: the full-scan walk, the lineage path, or both compared", "enum": [ "off", "on", "verify" ] }, "query_memory_bytes": { "type": "integer", "description": "the memory pool one read query runs under, and the allowance one load statement's retained read-reuse buffers are admitted against; tracked work past it is refused, and a raised value is memory one query or load may hold", "minimum": 1 }, "traversal_work_limit": { "type": "integer", "description": "the finite work budget shared by edge selections in one query; exhaustion terminates the query with an error", "maximum": 9223372036854775807, "minimum": 1 }, "write_max_bytes": { "type": "integer", "description": "the byte allowance for bounded writes by mutate, load and branch merge; entity data and materialized Blob payloads each have this independent allowance; lowering it preserves the existing per-type, per-operation and per-chunk scopes; a value raised above the default is held in memory as one typed batch at commit", "minimum": 1 } }, "additionalProperties": false }, "SnapshotDatasetOutput": { "type": "object", "required": [ "entity_kind", "type_name", "dataset_path", "published_dataset_version", "entity_count" ], "properties": { "dataset_path": { "type": "string" }, "entity_count": { "type": "integer", "format": "int64", "minimum": 0 }, "entity_kind": { "$ref": "#/components/schemas/EntityKind" }, "native_dataset_branch": { "type": [ "string", "null" ] }, "published_dataset_version": { "type": "integer", "format": "int64", "minimum": 0 }, "type_name": { "type": "string" } } }, "SnapshotOutput": { "type": "object", "required": [ "graph_branch", "graph_manifest_version", "internal_schema_version", "datasets" ], "properties": { "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotDatasetOutput" } }, "graph_branch": { "type": "string" }, "graph_manifest_version": { "type": "integer", "format": "int64", "minimum": 0 }, "internal_schema_version": { "type": "integer", "format": "int32", "description": "The on-disk internal-schema (storage-format) version this graph's branch\nis stamped at. It may be below the version the binary writes (the\n`internal_schema_version` of `GET /healthz`): normal open serves a range\nof versions, and a branch in that range takes the current one at its\nfirst publish.", "minimum": 0 } } }, "StartOptimizeRequest": { "type": "object", "description": "`POST /graphs/{graph_id}/operations/optimize`.", "required": [ "operation_id" ], "properties": { "datasets": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only these datasets, each named by its type key (`node:`,\n`edge:`), in this order." }, "max_gate_hold_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "How long writers to main wait at most, within the server's ceiling.", "minimum": 0 }, "operation_id": { "type": "string", "description": "A canonical ULID the caller chose; a repeated submission with the same\nrequest answers the existing record." } }, "additionalProperties": false }, "SuggestionOutput": { "type": "object", "description": "Non-overlapping edits against the original request source.", "required": [ "applicability", "edits" ], "properties": { "applicability": { "$ref": "#/components/schemas/Applicability" }, "edits": { "type": "array", "items": { "$ref": "#/components/schemas/TextEditOutput" } } } }, "SystemColumnsOutput": { "type": "object", "description": "A graph's system column spellings (see `SchemaOutput::system_columns`).", "required": [ "id", "src", "dst" ], "properties": { "dst": { "type": "string" }, "id": { "type": "string" }, "src": { "type": "string" } } }, "TextEditOutput": { "type": "object", "description": "A UTF-8 byte range in the original source, with an exclusive end.", "required": [ "start", "end", "replacement" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "replacement": { "type": "string" }, "start": { "type": "integer", "minimum": 0 } } }, "WriterFencedOutput": { "type": "object", "description": "The writer epochs of a publish or claim a claimed branch refused. `held`\nis the serving process's epoch, absent when it holds none; `read` is the\nepoch a refused claim read; `current` is the branch's epoch.", "required": [ "current" ], "properties": { "current": { "type": "integer", "format": "int64", "minimum": 0 }, "held": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "read": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } } }, "securitySchemes": { "bearer_token": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "access", "description": "Actions available to the authenticated actor" }, { "name": "blobs", "description": "Graph Blob values and conditional byte delivery" }, { "name": "branches", "description": "Graph branches and merges" }, { "name": "changes", "description": "Bounded graph differences and change feeds" }, { "name": "cluster", "description": "Cluster deployment planning and execution" }, { "name": "commits", "description": "Graph commit history and publication" }, { "name": "health", "description": "Process health and readiness probes" }, { "name": "operations", "description": "Recorded operations: optimize through the serving owner, looked up and cancelled by id" }, { "name": "management", "description": "Server graph inventory and OAuth resource metadata" }, { "name": "mutations", "description": "Graph mutations and data loading" }, { "name": "queries", "description": "Inline and stored queries, and graph exports" }, { "name": "schema", "description": "Accepted graph schemas" }, { "name": "snapshots", "description": "Coherent graph snapshot metadata" } ] }