{ "openapi": "3.1.0", "info": { "title": "Lorebase Keeper", "description": "REST API of Lorebase: versioned ontology and knowledge graph. Errors use RFC 9457 problem details.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" }, "version": "0.3.1" }, "paths": { "/healthz": { "get": { "tags": [ "health" ], "summary": "Liveness", "description": "The process answers requests. Never touches dependencies.", "operationId": "healthz_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Liveness" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readiness", "description": "Dependencies are usable: the database is reachable and migrations are current.", "operationId": "readyz_readyz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A dependency check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } } } } }, "/api/v1/auth/whoami": { "get": { "tags": [ "auth" ], "summary": "Identify the caller", "description": "Who the credential of this request belongs to, with the ids grants may name and, for an\nAPI key, its daily quotas.", "operationId": "whoami_api_v1_auth_whoami_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No valid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/auth/login": { "get": { "tags": [ "auth" ], "summary": "Start a browser sign-in", "description": "Send the browser to the identity provider (authorization code flow with PKCE). The\nsign-in state travels in a short-lived, encrypted, HttpOnly cookie.", "operationId": "login_api_v1_auth_login_get", "parameters": [ { "name": "return_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Path on the web app's origin to return to after signing in.", "title": "Return To" }, "description": "Path on the web app's origin to return to after signing in." } ], "responses": { "302": { "description": "Redirect to the identity provider." }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "return_to is not a path of the web app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Web sign-in is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The identity provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/auth/callback": { "get": { "tags": [ "auth" ], "summary": "Finish a browser sign-in", "description": "The provider's redirect after sign-in. Checks state, redeems the code with the PKCE\nverifier, verifies the ID token and its nonce, maps the user to a principal as for bearer\ntokens, and starts a session with a new id.", "operationId": "callback_api_v1_auth_callback_get", "responses": { "302": { "description": "Signed in: redirect to the return path with the session cookie. Failed: redirect to the app's error path with ?error=." }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Web sign-in is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/auth/session": { "get": { "tags": [ "auth" ], "summary": "Describe the browser session", "description": "Who is signed in, until when, and the CSRF token the web app sends with unsafe\nrequests. Requests authenticated by an API key or bearer token get 401.", "operationId": "session_info_api_v1_auth_session_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionInfo" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "No valid session cookie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Web sign-in is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Sign out of the browser session", "description": "End the session of the cookie (CSRF token required), clear the cookie and return the\nprovider's end-session URL for RP-initiated logout. Without a session it only clears the\ncookie.", "operationId": "logout_api_v1_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResult" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "CSRF check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Web sign-in is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/api-keys": { "post": { "tags": [ "admin" ], "summary": "Create an API key", "description": "Create a key bound to a service principal and limited to this Domain.\n\nUnless `principal_id` names an existing service principal, a new one is created and given\n`role` in the Domain. The secret in `key` is shown once.", "operationId": "create_api_key_api_v1_domains__domain_id__api_keys_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "get": { "tags": [ "admin" ], "summary": "List the API keys of a Domain", "description": "Keys limited to this Domain, oldest first, including revoked and expired ones.", "operationId": "list_api_keys_api_v1_domains__domain_id__api_keys_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ApiKeyOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/api-keys/{key_id}": { "delete": { "tags": [ "admin" ], "summary": "Revoke an API key", "description": "Revoke a key of this Domain. Revoking a revoked key succeeds.", "operationId": "revoke_api_key_api_v1_domains__domain_id__api_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/principals": { "get": { "tags": [ "admin" ], "summary": "List principals", "description": "Users and service principals of the installation, oldest first.", "operationId": "list_principals_api_v1_principals_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/PrincipalType" }, { "type": "null" } ], "title": "Type" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PrincipalOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/grants": { "post": { "tags": [ "admin" ], "summary": "Grant a role", "description": "Give a principal or group a role in the Domain, optionally narrowed to a scope.", "operationId": "create_grant_api_v1_domains__domain_id__grants_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrant" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "get": { "tags": [ "admin" ], "summary": "List grants", "description": "Grants of the Domain, oldest first.", "operationId": "list_grants_api_v1_domains__domain_id__grants_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_GrantOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/grants/{grant_id}": { "delete": { "tags": [ "admin" ], "summary": "Revoke a grant", "description": "Remove a grant from the Domain.", "operationId": "revoke_grant_api_v1_domains__domain_id__grants__grant_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Grant Id" } } ], "responses": { "204": { "description": "Successful Response" }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/audit": { "get": { "tags": [ "admin" ], "summary": "Read the audit log", "description": "Audit entries of the Domain, newest first.", "operationId": "list_audit_api_v1_domains__domain_id__audit_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AuditEntryOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/audit/verify": { "get": { "tags": [ "admin" ], "summary": "Verify the audit chain", "description": "Recompute the hash chain of the Domain's audit log and report the first broken entry.\n\nEntries are read in batches, so a long chain costs time, not memory. The answer is 200\nwhether the chain is intact or not; `intact` and `first_broken` tell which.", "operationId": "verify_audit_api_v1_domains__domain_id__audit_verify_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Start after this entry, trusting it as the anchor (a `last_seq` of an earlier verification); 0 verifies the whole chain.", "default": 0, "title": "After Seq" }, "description": "Start after this entry, trusting it as the anchor (a `last_seq` of an earlier verification); 0 verifies the whole chain." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerificationOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains": { "post": { "tags": [ "domains" ], "summary": "Create a Domain", "description": "Create a Domain with an initial Revision on its default branch (protected by default).\n\nWith an `Idempotency-Key`, retrying a create that succeeded returns the Domain with\nstatus 200 and `Idempotent-Replayed: true`.", "operationId": "create_domain_api_v1_domains_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "get": { "tags": [ "domains" ], "summary": "List Domains", "description": "Domains whose schema the caller may read (also through grants narrowed to Kinds that\nare invisible to it otherwise), ordered by id.", "operationId": "list_domains_api_v1_domains_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DomainOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}": { "get": { "tags": [ "domains" ], "summary": "Get a Domain", "description": "The Domain, the head Revision of its default branch, its ignored settings and what the\ncaller may do with it.", "operationId": "get_domain_api_v1_domains__domain_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "patch": { "tags": [ "domains" ], "summary": "Update Domain metadata and settings", "description": "Change the display name, the description or allowlisted settings members (`extraction`).\nThey are not versioned; setting changes are audited with their values before and after.", "operationId": "update_domain_api_v1_domains__domain_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "delete": { "tags": [ "domains" ], "summary": "Delete a Domain", "description": "Delete the Domain with all its Revisions, branches, materialized rows and grants.", "operationId": "delete_domain_api_v1_domains__domain_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "confirm", "in": "query", "required": true, "schema": { "type": "string", "description": "The Domain id, repeated to confirm.", "title": "Confirm" }, "description": "The Domain id, repeated to confirm." } ], "responses": { "204": { "description": "Successful Response" }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/schema/suggestions": { "get": { "tags": [ "schema" ], "summary": "List schema suggestions", "description": "Kinds, Attributes and Relations extraction found outside the schema, with support,\nexamples, samples and, for Attributes, the type their samples suggest.", "operationId": "list_suggestions_api_v1_domains__domain_id__schema_suggestions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "pending", "accepted", "rejected" ], "type": "string" } }, { "type": "null" } ], "title": "Status" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "kind", "attribute", "relation", "kind_alias", "attribute_alias", "value_alias", "attribute_description" ], "type": "string" } }, { "type": "null" } ], "title": "Type" } }, { "name": "all", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also those below `schema.suggestions.min_support`.", "default": false, "title": "All" }, "description": "Also those below `schema.suggestions.min_support`." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SuggestionOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or suggestion not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A suggestion was accepted already.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, a suggestion the schema has meanwhile, or accepted suggestions that do not form a valid schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "A branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema/suggestions:decide": { "post": { "tags": [ "schema" ], "summary": "Accept or reject schema suggestions", "description": "Reject or reset suggestions; accept some as one schema change Proposal.", "operationId": "decide_suggestions_api_v1_domains__domain_id__schema_suggestions_decide_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideSuggestionsIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideSuggestionsOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or suggestion not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A suggestion was accepted already.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, a suggestion the schema has meanwhile, or accepted suggestions that do not form a valid schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "A branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema/suggestions:merge": { "post": { "tags": [ "schema" ], "summary": "Merge stored variants of schema suggestions", "description": "Fold pending Attribute suggestions that are variants of one another, with the same\nsimilarity rules as new observations (idempotent).", "operationId": "merge_suggestions_api_v1_domains__domain_id__schema_suggestions_merge_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeSuggestionsOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or suggestion not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema": { "get": { "tags": [ "schema" ], "summary": "Get the schema", "description": "The schema at a branch head or at a Revision, as JSON or YAML.", "operationId": "get_schema_api_v1_domains__domain_id__schema_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default: the default branch.", "title": "Branch" }, "description": "Default: the default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id, tag or branch name.", "title": "At" }, "description": "Revision id, tag or branch name." }, { "name": "format", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "json", "yaml" ], "type": "string" }, { "type": "null" } ], "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaOut" } }, "text/yaml": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision or element not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Protected branch or moved head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The change set is invalid; `issues` locate why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema/{section}/{name}": { "get": { "tags": [ "schema" ], "summary": "Get a schema element", "description": "A Kind, Relation, Trait, Operation, Derivation, Source or Lens by api name or id.\n\nBuilt-in Operations (`create_supplier`, `link_supplied_by`, `import_records`, ...) are\ndescribed with the parameters derived from the schema.", "operationId": "get_element_api_v1_domains__domain_id__schema__section___name__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "section", "in": "path", "required": true, "schema": { "enum": [ "kinds", "relations", "traits", "operations", "derivations", "sources", "lenses" ], "type": "string", "title": "Section" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default: the default branch.", "title": "Branch" }, "description": "Default: the default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id, tag or branch name.", "title": "At" }, "description": "Revision id, tag or branch name." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Element Api V1 Domains Domain Id Schema Section Name Get" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision or element not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Protected branch or moved head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The change set is invalid; `issues` locate why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema:validate": { "post": { "tags": [ "schema" ], "summary": "Validate a schema change set", "description": "Static validation of a document or patch against the schema of a branch or Revision.\n\nIssue paths point into the schema document (api names). Nothing is written.", "operationId": "validate_schema_api_v1_domains__domain_id__schema_validate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "Branch" }, "description": "For YAML bodies." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "At" }, "description": "For YAML bodies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SchemaValidateRequest" }, { "type": "string" } ], "description": "JSON change set, or the full schema document as text/yaml (options as query parameters).", "title": "Payload" } }, "text/yaml": { "schema": { "type": "string", "description": "Full schema document." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaValidationOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision or element not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Protected branch or moved head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The change set is invalid; `issues` locate why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}/schema/changes": { "post": { "tags": [ "schema" ], "summary": "Apply a schema change set", "description": "Apply a change set as one Revision (data migrations included), or dry-run it.\n\nA dry run returns the element changes, the number of data changes and the validation\nissues without committing. Protected branches refuse direct changes (409).", "operationId": "apply_schema_changes_api_v1_domains__domain_id__branches__branch__schema_changes_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } }, { "name": "dry_run", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "Dry Run" }, "description": "For YAML bodies." }, { "name": "cascade", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "Cascade" }, "description": "For YAML bodies." }, { "name": "message", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "Message" }, "description": "For YAML bodies." }, { "name": "expected_head", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For YAML bodies.", "title": "Expected Head" }, "description": "For YAML bodies." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SchemaChangeRequest" }, { "type": "string" } ], "description": "JSON change set, or the full schema document as text/yaml (options as query parameters).", "title": "Payload" } }, "text/yaml": { "schema": { "type": "string", "description": "Full schema document." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaChangeOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision or element not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Protected branch or moved head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The change set is invalid; `issues` locate why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}/rebase-tags": { "post": { "tags": [ "schema" ], "summary": "Take the default branch's sensitivity tags", "description": "Give a branch forked before the default branch tagged an Attribute the tags it lacks.\n\nOne schema change adds, to every Attribute the branch shares with the default branch, the\ntags the default branch gives it, and to derived Attributes the tags of what they read;\nno tag is removed. It recomputes the titles and search vectors of the Kinds it changes,\nso verification no longer reports them as `sensitivity_stale`. A branch that already has\nthe tags gives `no_op`. Protected branches refuse the change (409) unless `rows_only`:\nthen only a `store.sensitivity_refresh` job is queued, which rewrites those rows in\nbatches and leaves the schema as it is. `tags` lists the tags added only to callers\nwho may read the default branch's schema (empty otherwise).", "operationId": "rebase_tags_api_v1_domains__domain_id__branches__branch__rebase_tags_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebaseTagsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebaseTagsOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision or element not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Protected branch or moved head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The change set is invalid; `issues` locate why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/schema:infer": { "post": { "tags": [ "schema" ], "summary": "Propose a schema from tables or data files", "description": "Profile the uploaded files (CSV, TSV, JSON, JSON Lines, Parquet) or the tables of a\nPostgres, MySQL, MariaDB or SQL Server source and propose Kinds, typed Attributes, keys and\nRelations with evidence. Deterministic and model-free; nothing is written.", "operationId": "infer_api_v1_domains__domain_id__schema_infer_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "json", "yaml" ], "type": "string" }, { "type": "null" } ], "title": "Format" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lorebase_keeper__routes__schema_inference__ProposalOut" } }, "text/yaml": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks schema.write in the Domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "A file or the upload is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid files, source or options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The source database cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "CSV, TSV, JSON, JSON Lines or Parquet files, read by suffix; the file name is the table name." }, "options": { "type": "string", "description": "JSON object of InferenceOptions overrides." }, "records_path": { "type": "string", "description": "Dotted keys of the records array of JSON documents that hold it under a key, e.g. data.items." } }, "required": [ "files" ] } }, "application/json": { "schema": { "type": "object", "properties": { "postgres": { "type": "object", "properties": { "dsn": { "type": "string", "example": "secret://env/ERP_DSN" }, "schema": { "type": "string", "default": "public" }, "tables": { "type": "array", "items": { "type": "string" } } }, "required": [ "dsn" ] }, "mysql": { "type": "object", "description": "A MySQL or MariaDB source, in place of postgres.", "properties": { "dsn": { "type": "string", "example": "secret://env/ERP_DSN" }, "schema": { "type": "string" }, "tables": { "type": "array", "items": { "type": "string" } } }, "required": [ "dsn" ] }, "mssql": { "type": "object", "description": "A SQL Server source, in place of postgres.", "properties": { "dsn": { "type": "string", "example": "secret://env/ERP_DSN" }, "schema": { "type": "string" }, "tables": { "type": "array", "items": { "type": "string" } } }, "required": [ "dsn" ] }, "options": { "type": "object", "description": "InferenceOptions overrides." } } } } } } } }, "/api/v1/domains/{domain_id}/schema:preview": { "post": { "tags": [ "schema" ], "summary": "Read the first rows of uploaded data files", "description": "Return the first rows of each uploaded file (CSV, TSV, JSON, JSON Lines, Parquet) as\nrecords, under the permission and size limits of `schema:infer`. Nothing is stored; a\nclient uses it to show the rows of a format it cannot read itself.", "operationId": "preview_api_v1_domains__domain_id__schema_preview_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "rows", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Rows per file; default and cap are settings.", "title": "Rows" }, "description": "Rows per file; default and cap are settings." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks schema.write in the Domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "A file or the upload is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid files, source or options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The source database cannot be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "CSV, TSV, JSON, JSON Lines or Parquet files, read by suffix." }, "records_path": { "type": "string", "description": "Dotted keys of the records array of JSON documents that hold it under a key, e.g. data.items." } }, "required": [ "files" ] } } } } } }, "/api/v1/domains/{domain_id}/operations/{operation}/execute": { "post": { "tags": [ "operations" ], "summary": "Execute an Operation", "description": "Validate parameters, compute the edits and commit them as a Revision (or dry-run).\n\nAn Operation that needs review is a 409 `review-required` unless the request names a\n`task`: then it runs on a task branch and the answer is 202 with the Proposal.", "operationId": "execute_operation_api_v1_domains__domain_id__operations__operation__execute_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "operation", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Operation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "202": { "description": "The Operation needs review and ran on a task branch; a Proposal carries the edits (`status`: `proposed`, `merged` or `conflicts`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWriteOut" } } } }, "409": { "description": "Review required (`review-required`, with `next` hints), head moved (`stale-head`), idempotency key reused with other parameters (`idempotency-conflict`) or too many task branches (`agent-branch-limit`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid parameters or violations (`issues`, `edits`), a precondition that does not hold (`precondition-failed`, with the expression and its position), or expressions not enabled (`expressions-not-enabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records": { "get": { "tags": [ "read" ], "summary": "List Records of a Kind", "description": "Records of a Kind filtered with the DSL, ordered and paginated by keyset.", "operationId": "list_records_api_v1_domains__domain_id__kinds__kind__records_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, { "name": "where", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 65536 }, { "type": "null" } ], "description": "DSL predicate as JSON (design 8.2).", "title": "Where" }, "description": "DSL predicate as JSON (design 8.2)." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated `name[:asc|desc]` terms.", "title": "Order By" }, "description": "Comma-separated `name[:asc|desc]` terms." }, { "name": "select", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field names.", "title": "Select" }, "description": "Comma-separated field names." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records/{key}/links/{relation}": { "get": { "tags": [ "read" ], "summary": "List the Links of a Record along a Relation", "description": "Links of the Record along `relation`, a forward or inverse api name, by far key.", "operationId": "list_record_links_api_v1_domains__domain_id__kinds__kind__records__key__links__relation__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "relation", "in": "path", "required": true, "schema": { "type": "string", "title": "Relation" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records/{key}": { "get": { "tags": [ "read" ], "summary": "Get a Record by key", "description": "One Record, optionally with its Link counts and the lineage of its values.", "operationId": "get_record_api_v1_domains__domain_id__kinds__kind__records__key__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, { "name": "links", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Add Link counts per Relation.", "default": false, "title": "Links" }, "description": "Add Link counts per Relation." }, { "name": "lineage", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Add the provenance of each value.", "default": false, "title": "Lineage" }, "description": "Add the provenance of each value." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records/{key}/history": { "get": { "tags": [ "read" ], "summary": "History of a Record", "description": "Revisions that changed the Record on the branch, newest first, with the Attributes each\nchanged and their provenance, from the branch history; with `at`, the changes up to that\nRevision.", "operationId": "get_record_history_api_v1_domains__domain_id__kinds__kind__records__key__history_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, { "name": "values", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Add the values before and after each change.", "default": false, "title": "Values" }, "description": "Add the values before and after each change." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordHistoryOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records/{key}/lineage": { "get": { "tags": [ "read" ], "summary": "Lineage of a Record", "description": "Where each value of the Record came from: provenance, Revision, Source, Operation,\nextraction evidence and Proposal. At the branch head, or at `at` (from a snapshot).", "operationId": "get_record_lineage_api_v1_domains__domain_id__kinds__kind__records__key__lineage_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordLineageOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/relations/{relation}/links": { "get": { "tags": [ "read" ], "summary": "List the Links of a Relation", "description": "Links of a Relation (either api name) ordered by `(from_key, to_key)`.", "operationId": "list_relation_links_api_v1_domains__domain_id__relations__relation__links_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "relation", "in": "path", "required": true, "schema": { "type": "string", "title": "Relation" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision.", "title": "At" }, "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, { "name": "from_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only Links from this key.", "title": "From Key" }, "description": "Only Links from this key." }, { "name": "to_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only Links to this key.", "title": "To Key" }, "description": "Only Links to this key." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/query": { "post": { "tags": [ "read" ], "summary": "Query Records with the DSL", "description": "Run a DSL query (design 8.2): filters, Relation predicates, includes, aggregates. The\nanswer says how complete it can be (`coverage`, design 8.11) unless the request turns it\noff.", "operationId": "query_records_api_v1_domains__domain_id__query_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/traverse": { "post": { "tags": [ "read" ], "summary": "Traverse Relations from a Record", "description": "Follow a path of Relations, with a filter and a cap per hop (design 8.3).", "operationId": "traverse_api_v1_domains__domain_id__traverse_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraverseRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraverseResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/neighborhood": { "post": { "tags": [ "read" ], "summary": "Neighborhood of seed Records", "description": "Breadth-first expansion from seed Records within depth, node and edge caps.", "operationId": "neighborhood_api_v1_domains__domain_id__neighborhood_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeighborhoodRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeighborhoodResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/search": { "post": { "tags": [ "read" ], "summary": "Search Records", "description": "Lexical, semantic (caller-supplied vector) or hybrid search (design 8.4).", "operationId": "search_records_api_v1_domains__domain_id__search_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/resolve": { "post": { "tags": [ "read" ], "summary": "Resolve words to schema elements and values", "description": "Ground the words of a text in the schema and the indexed values (design 8.9): ranked\ncandidate Kinds, Attributes and values, each with the words it matched and, for values,\na ready-to-use predicate. No query is run and nothing is interpreted beyond matching.\nPhrases that matched nothing are listed in `coverage.unknown` and, where the operator\nturned it on, kept for vocabulary suggestions (design 8.10).", "operationId": "resolve_words_api_v1_domains__domain_id__resolve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/derivations:preview": { "post": { "tags": [ "derivations" ], "summary": "Preview a candidate Derivation", "description": "Evaluate a Derivation, as edited and not yet saved, on sample Records of its Kind.\n\nThe candidate schema is checked like a schema change; reading follows Record reads\n(permissions per Kind, masking of sensitive values). Nothing is written.", "operationId": "preview_derivation_api_v1_domains__domain_id__derivations_preview_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DerivationPreviewRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DerivationPreviewOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for a Kind the Derivation touches, or schema.read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or a candidate schema that fails validation (`issues` locate why).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/health": { "get": { "tags": [ "health" ], "summary": "Health of a Domain", "description": "Per Kind: Records, Links by Relation, constraint violations against the current schema,\nrequired-relation gaps, orphan Links, duplicates on unique and title Attributes, stale\nderived values and the last change; for the Kinds the caller may read.", "operationId": "domain_health_api_v1_domains__domain_id__health_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to examine; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to examine; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to examine (time travel, served from a snapshot).", "title": "At" }, "description": "Revision id or tag to examine (time travel, served from a snapshot)." }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "markdown" ], "type": "string", "description": "`markdown` renders the report as text.", "default": "json", "title": "Format" }, "description": "`markdown` renders the report as text." } ], "responses": { "200": { "description": "The report in JSON, or markdown with `format=markdown`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainHealthOut" } }, "text/markdown; charset=utf-8": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Kind not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The scan exceeded its statement timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/health": { "get": { "tags": [ "health" ], "summary": "Health of a Kind", "description": "The checks of the Domain report for one Kind, with the Relations it takes part in.", "operationId": "kind_health_api_v1_domains__domain_id__kinds__kind__health_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to examine; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to examine; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to examine (time travel, served from a snapshot).", "title": "At" }, "description": "Revision id or tag to examine (time travel, served from a snapshot)." }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "markdown" ], "type": "string", "description": "`markdown` renders the report as text.", "default": "json", "title": "Format" }, "description": "`markdown` renders the report as text." } ], "responses": { "200": { "description": "The report in JSON, or markdown with `format=markdown`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KindHealthOut" } }, "text/markdown; charset=utf-8": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Kind not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The scan exceeded its statement timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/context": { "post": { "tags": [ "agents" ], "summary": "Context pack for an agent", "description": "Seed Records, their neighborhood, schema, recent changes and lineage within a budget.", "operationId": "context_pack_api_v1_domains__domain_id__context_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextRequest" } } } }, "responses": { "200": { "description": "The pack in JSON, or markdown with `format: markdown`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextPackOut" } }, "text/markdown; charset=utf-8": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for what is read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/kinds/{kind}/records/{key}/explain": { "get": { "tags": [ "agents" ], "summary": "Explain a Record", "description": "Creation, per-Attribute lineage, Links with their origin and Proposals of a Record.", "operationId": "explain_api_v1_domains__domain_id__kinds__kind__records__key__explain_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "title": "Kind" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Branch to read; default: the Domain's default branch.", "title": "Branch" }, "description": "Branch to read; default: the Domain's default branch." }, { "name": "at", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag to read at (time travel, served from a snapshot).", "title": "At" }, "description": "Revision id or tag to read at (time travel, served from a snapshot)." }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "markdown" ], "type": "string", "default": "json", "title": "Format" } } ], "responses": { "200": { "description": "The explanation in JSON, or markdown with `format=markdown`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainOut" } }, "text/markdown; charset=utf-8": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for what is read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, Revision, Kind or Record not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/webhooks": { "post": { "tags": [ "webhooks" ], "summary": "Create a webhook", "description": "Register an endpoint for the Domain's events; the secret is returned once.", "operationId": "create_webhook_api_v1_domains__domain_id__webhooks_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhook" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks domain.settings, or a clearance it gives the webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "409": { "description": "The Domain has the most webhooks allowed, or webhooks.encryption_key is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "webhooks" ], "summary": "List webhooks", "description": "Webhooks of the Domain, oldest first (secrets are never shown again).", "operationId": "list_webhooks_api_v1_domains__domain_id__webhooks_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks domain.settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/webhooks/{webhook_id}": { "patch": { "tags": [ "webhooks" ], "summary": "Change the clearances of a webhook", "description": "Replace the sensitivity clearances of a webhook; only added ones need their permission.", "operationId": "update_webhook_api_v1_domains__domain_id__webhooks__webhook_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks domain.settings, or a clearance it gives the webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook", "description": "Remove a webhook and its pending deliveries.", "operationId": "delete_webhook_api_v1_domains__domain_id__webhooks__webhook_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "204": { "description": "Successful Response" }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks domain.settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/sources:preview": { "post": { "tags": [ "sources" ], "summary": "Preview the expression mappings of a candidate Source", "description": "Evaluate the `expression` mappings of a Source, as edited and not yet saved, on sample\nrows. Nothing is read from the Source and nothing is written.", "operationId": "preview_source_api_v1_domains__domain_id__sources_preview_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcePreviewRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcePreviewOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks schema.read for the branch and for the Source's target Kind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or a candidate schema that fails validation (`issues` locate why).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/sources/{source}/sync": { "post": { "tags": [ "sources" ], "summary": "Synchronize a Source", "description": "Queue a synchronization of the Source for Scribe.", "operationId": "sync_source_api_v1_domains__domain_id__sources__source__sync_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "Source" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SyncRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncQueued" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks source.sync, or pii.import for a Source mapping vault Attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or Source not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/sources/{source}/runs": { "get": { "tags": [ "sources" ], "summary": "List Source runs", "description": "Runs of the Source, newest first.", "operationId": "list_source_runs_api_v1_domains__domain_id__sources__source__runs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "Source" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SourceRunOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or Source not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/vault/erase": { "post": { "tags": [ "vault" ], "summary": "Erase personal data from the vault", "description": "Erase the vaulted values of a Record or a value in a Kind, on every Revision.", "operationId": "erase_api_v1_domains__domain_id__vault_erase_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EraseIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EraseOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks pii.erase on the Domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Kind not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Erasure by value needs the vault keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The vault of the Domain stayed locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/vault/keys": { "get": { "tags": [ "vault" ], "summary": "Show which keys the vault rows use", "description": "Rows by encryption key and fingerprint key, and the earlier keys that can be removed.", "operationId": "vault_keys_api_v1_vault_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultKeysOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an installation administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The vault is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/vault/rotate": { "post": { "tags": [ "vault" ], "summary": "Queue a vault key rotation", "description": "Queue the job that makes the rows stored under earlier keys again under the current\nones.", "operationId": "rotate_vault_api_v1_vault_rotate_post", "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationQueued" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an installation administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The vault is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/domains/{domain_id}/documents": { "post": { "tags": [ "documents" ], "summary": "Upload a document for extraction", "description": "Store a document (multipart upload or allowlisted URL) and queue its extraction; with\na `source_key`, new bytes are a new version of the key's document.", "operationId": "upload_document_api_v1_domains__domain_id__documents_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploaded" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The document is retired (`document-retired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unsupported or invalid document, URL or fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The URL could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploaded" } } }, "description": "OK" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "extract": { "type": "boolean" }, "tiers": { "type": "string", "description": "JSON list, e.g. [0, 1]" }, "source_key": { "type": "string", "description": "Stable identity: new bytes are a new version." } }, "required": [ "file" ] } }, "application/json": { "schema": { "additionalProperties": false, "description": "JSON body: a document fetched from an allowlisted URL.", "properties": { "url": { "maxLength": 2000, "minLength": 1, "title": "Url", "type": "string" }, "filename": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Name to store; default: the URL's last segment.", "title": "Filename" }, "extract": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Queue an extraction job.", "title": "Extract" }, "tiers": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Extraction tiers (0, 1, 2).", "title": "Tiers" }, "source_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable identity (path, URL or external id): new bytes under the same key are a new version of its document.", "title": "Source Key" } }, "required": [ "url" ], "title": "DocumentFromUrl", "type": "object" } } } } }, "get": { "tags": [ "documents" ], "summary": "List documents", "description": "Documents of the Domain, newest first; with `source_key`, the versions of that key.", "operationId": "list_documents_api_v1_domains__domain_id__documents_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "source_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the versions of this key (trimmed, exact).", "title": "Source Key" }, "description": "Only the versions of this key (trimmed, exact)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DocumentOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The document is retired (`document-retired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unsupported or invalid document, URL or fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The URL could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/documents/{document_id}": { "get": { "tags": [ "documents" ], "summary": "Get a document", "description": "The document's metadata and its extraction jobs, newest first.", "operationId": "get_document_api_v1_domains__domain_id__documents__document_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetailOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The document is retired (`document-retired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unsupported or invalid document, URL or fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The URL could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/documents/{document_id}/versions": { "get": { "tags": [ "documents" ], "summary": "List the versions of a document", "description": "The versions of the document's `source_key`, newest first (only itself when keyless).", "operationId": "list_document_versions_api_v1_domains__domain_id__documents__document_id__versions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DocumentOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The document is retired (`document-retired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The document is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unsupported or invalid document, URL or fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "The URL could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/documents/{document_id}/retirement": { "post": { "tags": [ "documents" ], "summary": "Retire a document", "description": "Retire a document: it stays readable, is never extracted again, and values whose\nevidence was this document raise `stale` reconciliation candidates.", "operationId": "retire_document_api_v1_domains__domain_id__documents__document_id__retirement_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirementIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRetired" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid reason, or `confirm` is not the document id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/documents/{document_id}/purge": { "post": { "tags": [ "documents" ], "summary": "Purge a document (irreversible)", "description": "Delete a document's bytes, text, chunks and quotes, keeping its provenance (module\ndoc); retires it first if needed.", "operationId": "purge_document_api_v1_domains__domain_id__documents__document_id__purge_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPurged" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid reason, or `confirm` is not the document id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/documents/{document_id}/text": { "get": { "tags": [ "documents" ], "summary": "Get the parsed text of a document", "description": "The text Scribe parsed from the document; extraction evidence offsets index it.", "operationId": "get_document_text_api_v1_domains__domain_id__documents__document_id__text_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTextOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "304": { "description": "Not modified (`If-None-Match`)." }, "403": { "description": "The caller lacks the permission Domain-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or document not found, or not parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}/events": { "get": { "tags": [ "agents" ], "summary": "Stream the Revisions of a branch (Server-Sent Events)", "description": "Revisions committed on the branch from now on, or after `Last-Event-ID`.", "operationId": "branch_events_api_v1_domains__domain_id__branches__branch__events_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } }, { "name": "kinds", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Only events changing these Kinds (repeated or comma-separated).", "title": "Kinds" }, "description": "Only events changing these Kinds (repeated or comma-separated)." }, { "name": "last_event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resume after this event id (for clients that cannot set headers).", "title": "Last Event Id" }, "description": "Resume after this event id (for clients that cannot set headers)." }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last-Event-Id" } } ], "responses": { "200": { "description": "`event: revision` messages whose `data` is a RevisionEventOut and whose `id` is the event sequence; comment lines as heartbeats.", "content": { "text/event-stream": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}/changes": { "get": { "tags": [ "agents" ], "summary": "Revisions of a branch since a Revision", "description": "First-parent Revisions after `since`, oldest first; continue with `next_since`.", "operationId": "branch_changes_api_v1_domains__domain_id__branches__branch__changes_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Revision id or tag; default: the latest Revisions.", "title": "Since" }, "description": "Revision id or tag; default: the latest Revisions." }, { "name": "kinds", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Only events changing these Kinds (repeated or comma-separated).", "title": "Kinds" }, "description": "Only events changing these Kinds (repeated or comma-separated)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesFeedPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." }, "409": { "description": "`since` is not reachable from the head.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/items": { "get": { "tags": [ "proposals" ], "summary": "List the items of an extraction Proposal", "description": "Items in proposal order (Records, values, Links), with evidence and match details.", "operationId": "list_items_api_v1_domains__domain_id__proposals__proposal_id__items_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "pending", "accepted", "rejected" ], "type": "string" } }, { "type": "null" } ], "title": "Status" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Kind or Relation api names (or ids).", "title": "Kind" }, "description": "Kind or Relation api names (or ids)." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "record", "value", "link" ], "type": "string" } }, { "type": "null" } ], "title": "Type" } }, { "name": "min_confidence", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Min Confidence" } }, { "name": "max_confidence", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.01, "minimum": 0 }, { "type": "null" } ], "title": "Max Confidence" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ItemOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or Proposal not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not an extraction Proposal, or not open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, unknown items, invalid edits, or the branch rejects the accepted items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The extraction branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/items:decide": { "post": { "tags": [ "proposals" ], "summary": "Accept or reject extraction items", "description": "Record decisions, re-materialize the extraction branch and refresh the Proposal.", "operationId": "decide_api_v1_domains__domain_id__proposals__proposal_id__items_decide_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain or Proposal not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not an extraction Proposal, or not open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, unknown items, invalid edits, or the branch rejects the accepted items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The extraction branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals": { "post": { "tags": [ "proposals" ], "summary": "Create a Proposal", "description": "Open a Proposal and compute its merge preview (Conflict count).\n\nThe merge policy comes from the Domain's `merge_policy` setting. With an\n`Idempotency-Key`, a retried create returns the Proposal with status 200 and\n`Idempotent-Replayed: true`.", "operationId": "create_proposal_api_v1_domains__domain_id__proposals_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetailOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "tags": [ "proposals" ], "summary": "List Proposals", "description": "Proposals the caller may read, newest first. With `assigned`, a page may hold fewer\nitems than asked while `next_cursor` is set.", "operationId": "list_proposals_api_v1_domains__domain_id__proposals_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProposalStatus" }, { "type": "null" } ], "title": "Status" } }, { "name": "origin", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProposalOrigin" }, { "type": "null" } ], "title": "Origin" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source branch.", "title": "Source" }, "description": "Source branch." }, { "name": "target", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target branch.", "title": "Target" }, "description": "Target branch." }, { "name": "author", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" } }, { "name": "assigned", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "me", "any", "none" ], "type": "string" }, { "type": "null" } ], "description": "`me`: Proposals the caller is an assignee of; `any`: with steward roles; `none`: without (design 10.7).", "title": "Assigned" }, "description": "`me`: Proposals the caller is an assignee of; `any`: with steward roles; `none`: without (design 10.7)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ProposalOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}": { "get": { "tags": [ "proposals" ], "summary": "Get a Proposal", "description": "The Proposal with its reviews, approval state, latest merge attempt and stewards.", "operationId": "get_proposal_api_v1_domains__domain_id__proposals__proposal_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetailOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "proposals" ], "summary": "Update a Proposal", "description": "Change the title or description of an open Proposal (its author or a maintainer).", "operationId": "update_proposal_api_v1_domains__domain_id__proposals__proposal_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetailOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/close": { "post": { "tags": [ "proposals" ], "summary": "Close a Proposal", "description": "Close without merging; the merge attempt is discarded and the target is unchanged.", "operationId": "close_proposal_api_v1_domains__domain_id__proposals__proposal_id__close_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetailOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/reviews": { "post": { "tags": [ "proposals" ], "summary": "Review a Proposal", "description": "Approve, request changes or comment.", "operationId": "review_proposal_api_v1_domains__domain_id__proposals__proposal_id__reviews_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewResult" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/merge": { "post": { "tags": [ "proposals" ], "summary": "Merge a Proposal", "description": "Run or re-run the merge with the stored resolutions.\n\n200 with the new target head when the merge committed (merge Revision with parents\n`[target head, source head]`, fast-forward, or nothing to do); 409 `merge-conflicts`\nwith the attempt when Conflicts remain. With an `Idempotency-Key`, retrying a merge that\ncommitted returns it again (`Idempotent-Replayed: true`).", "operationId": "merge_proposal_api_v1_domains__domain_id__proposals__proposal_id__merge_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MergeIn" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/conflicts": { "get": { "tags": [ "proposals" ], "summary": "List the Conflicts of a Proposal", "description": "The current merge attempt with one page of its Conflicts, ordered by id.", "operationId": "list_conflicts_api_v1_domains__domain_id__proposals__proposal_id__conflicts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conflict codes, comma-separated (`DV1,XS8`).", "title": "Kind" }, "description": "Conflict codes, comma-separated (`DV1,XS8`)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "open", "resolved" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictsOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/conflicts/{conflict_id}/resolution": { "post": { "tags": [ "proposals" ], "summary": "Resolve one Conflict", "description": "Store the resolution of one Conflict of the current attempt (no merge run).", "operationId": "resolve_conflict_api_v1_domains__domain_id__proposals__proposal_id__conflicts__conflict_id__resolution_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } }, { "name": "conflict_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conflict Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/proposals/{proposal_id}/conflicts:resolve": { "post": { "tags": [ "proposals" ], "summary": "Resolve Conflicts in bulk", "description": "Store several resolutions, re-run the merge and return the new attempt.", "operationId": "resolve_conflicts_api_v1_domains__domain_id__proposals__proposal_id__conflicts_resolve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Proposal Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveManyIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictsOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission, or self-approval refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, Proposal, branch or Conflict not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Proposal not open (`proposal-not-open`), approvals missing (`approvals-required`), Conflicts remain (`merge-conflicts`, with `attempt`), open contradictions block it (`reconciliation-open`, with `candidates`), too few stewards can approve it (`stewards-unavailable`), a branch is gone (`proposal-branch-missing`), duplicate or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request or resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The target branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation": { "get": { "tags": [ "reconciliation" ], "summary": "List reconciliation candidates", "description": "Candidates of a branch, newest first.", "operationId": "list_candidates_api_v1_domains__domain_id__reconciliation_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default: the default branch.", "title": "Branch" }, "description": "Default: the default branch." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CandidateType" }, { "type": "null" } ], "title": "Type" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CandidateStatus" }, { "type": "null" } ], "title": "Status" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Kind api name.", "title": "Kind" }, "description": "Kind api name." }, { "name": "attribute", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attribute api name (with kind).", "title": "Attribute" }, "description": "Attribute api name (with kind)." }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source identity of a claim, e.g. `source:src_...`.", "title": "Source" }, "description": "Source identity of a claim, e.g. `source:src_...`." }, { "name": "assigned", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "me", "any", "none" ], "type": "string" }, { "type": "null" } ], "description": "`me`: candidates the caller is an assignee of; `any`: with steward roles; `none`: without (design 10.7). A page may then hold fewer items than asked while `next_cursor` is set.", "title": "Assigned" }, "description": "`me`: candidates the caller is an assignee of; `any`: with steward roles; `none`: without (design 10.7). A page may then hold fewer items than asked while `next_cursor` is set." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ReconciliationCandidateOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation/{candidate_id}": { "get": { "tags": [ "reconciliation" ], "summary": "Get a reconciliation candidate", "description": "One candidate with its claims and last decision.", "operationId": "get_candidate_api_v1_domains__domain_id__reconciliation__candidate_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationCandidateOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation/{candidate_id}/resolution": { "post": { "tags": [ "reconciliation" ], "summary": "Resolve a candidate", "description": "Decide a candidate: the value is written by `update_{kind}` on its branch (proposed\nfrom a new branch `reconcile/{candidate}-{random}` when the branch needs review);\n`keep_current` writes nothing. `dry_run` reports the edits without deciding.", "operationId": "resolve_candidate_api_v1_domains__domain_id__reconciliation__candidate_id__resolution_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationResolveIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDecisionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation/{candidate_id}/dismissal": { "post": { "tags": [ "reconciliation" ], "summary": "Dismiss a candidate", "description": "Dismiss an open candidate; nothing is written. It can be reopened.", "operationId": "dismiss_candidate_api_v1_domains__domain_id__reconciliation__candidate_id__dismissal_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReasonIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDecisionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation/{candidate_id}/reopen": { "post": { "tags": [ "reconciliation" ], "summary": "Reopen a dismissed candidate", "description": "Open a dismissed candidate again.", "operationId": "reopen_candidate_api_v1_domains__domain_id__reconciliation__candidate_id__reopen_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Candidate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReasonIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDecisionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation:resolve": { "post": { "tags": [ "reconciliation" ], "summary": "Resolve candidates in bulk", "description": "Apply a policy, or dismiss, over at most `keeper.reconciliation.bulk_max` open\ncandidates; each is decided and audited on its own, and one that fails does not stop the\nothers.", "operationId": "resolve_candidates_api_v1_domains__domain_id__reconciliation_resolve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationBulkIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationBulkOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/reconciliation/sweeps": { "post": { "tags": [ "reconciliation" ], "summary": "Queue a reconciliation sweep", "description": "Queue a sweep of a branch for Scribe (job `reconcile_sweep`); an identical sweep that\nis queued or running is returned instead of a new one.", "operationId": "queue_sweep_api_v1_domains__domain_id__reconciliation_sweeps_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationSweepIn" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationSweepOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission or clearance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or candidate not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The candidate is not open (`candidate-not-open`), a decision on it awaits review in an open Proposal (`reconciliation-pending`), the Record's value changed since detection (`reconciliation-stale`), or the write needs review and its Proposal cannot be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request, or the value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}/log": { "get": { "tags": [ "revisions" ], "summary": "History of a branch", "description": "Revisions of a branch, newest first (first parents by default).", "operationId": "branch_log_api_v1_domains__domain_id__branches__branch__log_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } }, { "name": "all", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Every ancestor instead of the first-parent chain.", "default": false, "title": "All" }, "description": "Every ancestor instead of the first-parent chain." }, { "name": "origin_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only Revisions of this origin.", "title": "Origin Type" }, "description": "Only Revisions of this origin." }, { "name": "author", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only Revisions by this principal.", "title": "Author" }, "description": "Only Revisions by this principal." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/revisions/{revision}": { "get": { "tags": [ "revisions" ], "summary": "Get a Revision", "description": "A Revision by id, tag or branch name.", "operationId": "get_revision_api_v1_domains__domain_id__revisions__revision__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "title": "Revision" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/revisions/{revision}/counts": { "get": { "tags": [ "revisions" ], "summary": "Element counts per partition at a Revision", "description": "Schema elements, Records per Kind and Links per Relation at a Revision.", "operationId": "revision_counts_api_v1_domains__domain_id__revisions__revision__counts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "title": "Revision" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountsResponse" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/revisions/{revision}/changeset": { "get": { "tags": [ "revisions" ], "summary": "Changes of a Revision against its first parent", "description": "The stored changeset (design 6.3), with provenance per changed Attribute.", "operationId": "revision_changeset_api_v1_domains__domain_id__revisions__revision__changeset_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "title": "Revision" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/diff": { "get": { "tags": [ "revisions" ], "summary": "Diff two Revisions", "description": "Element changes from `from` to `to`, with a per-partition summary.", "operationId": "diff_api_v1_domains__domain_id__diff_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "Revision id, tag or branch.", "title": "From" }, "description": "Revision id, tag or branch." }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "Revision id, tag or branch.", "title": "To" }, "description": "Revision id, tag or branch." }, { "name": "kinds", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Kind api names (repeated or comma-separated).", "title": "Kinds" }, "description": "Kind api names (repeated or comma-separated)." }, { "name": "relations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Relation api names (repeated or comma-separated).", "title": "Relations" }, "description": "Relation api names (repeated or comma-separated)." }, { "name": "schema", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Include schema changes; default true unless filters are given.", "title": "Schema" }, "description": "Include schema changes; default true unless filters are given." }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "ndjson" ], "type": "string", "default": "json", "title": "Format" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesPage" } }, "application/x-ndjson": {} } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks data.read for the branch or Revision read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "304": { "description": "Not modified: If-None-Match names the current ETag." } } } }, "/api/v1/domains/{domain_id}/branches": { "get": { "tags": [ "branches" ], "summary": "List branches", "description": "Branches ordered by name.", "operationId": "list_branches_api_v1_domains__domain_id__branches_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_BranchOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "branches" ], "summary": "Create a branch", "description": "Create a materialized branch (a copy, or an overlay on its source) from a branch, tag\nor Revision.\n\nA copy of a large source (above `store.materialize.async_copy_min_rows` rows) is created\nas an overlay at once and copied by a background job: `materialization_status` is then\n`pending`, and the branch becomes `full` when it is `done`. With an `Idempotency-Key`,\nretrying a create that succeeded returns the branch with status 200 and\n`Idempotent-Replayed: true`.", "operationId": "create_branch_api_v1_domains__domain_id__branches_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/tags": { "get": { "tags": [ "branches" ], "summary": "List tags", "description": "Tags ordered by name.", "operationId": "list_tags_api_v1_domains__domain_id__tags_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_TagOut_" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "branches" ], "summary": "Create a tag", "description": "Tag a Revision. Tags never move.", "operationId": "create_tag_api_v1_domains__domain_id__tags_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/domains/{domain_id}/branches/{branch}": { "get": { "tags": [ "branches" ], "summary": "Get a branch", "description": "The branch head, protection flag and ahead/behind counts against the default branch.", "operationId": "get_branch_api_v1_domains__domain_id__branches__branch__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchDetail" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "tags": [ "branches" ], "summary": "Protect or unprotect a branch", "description": "Set the protection flag.", "operationId": "update_branch_api_v1_domains__domain_id__branches__branch__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchOut" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "branches" ], "summary": "Delete a branch", "description": "Delete a branch and its materialized rows; the default and protected branches stay.\n\nA large branch (above `store.materialize.async_delete_min_rows` rows) disappears at once\nand a background job deletes its rows; its name can be used again when that is done.", "operationId": "delete_branch_api_v1_domains__domain_id__branches__branch__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "branch", "in": "path", "required": true, "schema": { "type": "string", "title": "Branch" } } ], "responses": { "204": { "description": "Successful Response" }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller lacks the permission named in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Domain, branch, tag or Revision not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Exists already, protected, or over a limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" } } } }, "503": { "description": "The branch is locked by another writer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/trace/sessions": { "get": { "tags": [ "trace" ], "summary": "List agent trace sessions", "description": "Sessions with a step the caller may see, most recent activity first.", "operationId": "list_sessions_api_v1_trace_sessions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "actor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Only this principal.", "title": "Actor" }, "description": "Only this principal." }, { "name": "domain_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Only steps in this Domain.", "title": "Domain Id" }, "description": "Only steps in this Domain." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page size.", "title": "Limit" }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Opaque page cursor.", "title": "Cursor" }, "description": "Opaque page cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceSessionPage" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No visible step of that session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No database is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/trace/sessions/{session_id}": { "get": { "tags": [ "trace" ], "summary": "Timeline of an agent trace session", "description": "Calls and notes of one principal's session in order, as far as the caller may see\nthem.", "operationId": "get_session_api_v1_trace_sessions__session_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Session id as sent in the session header.", "title": "Session Id" }, "description": "Session id as sent in the session header." }, { "name": "actor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "description": "Principal whose steps are read; default: the caller. A session id names one session per principal.", "title": "Actor" }, "description": "Principal whose steps are read; default: the caller. A session id names one session per principal." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceTimeline" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No visible step of that session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No database is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/trace/sessions/{session_id}/notes": { "post": { "tags": [ "trace" ], "summary": "Attach a note to an agent trace session", "description": "Queue a note of the caller's session (written off the request path, like calls).", "operationId": "add_note_api_v1_trace_sessions__session_id__notes_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{1,128}$", "description": "Session id as sent in the session header.", "title": "Session Id" }, "description": "Session id as sent in the session header." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteIn" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteAccepted" } } } }, "default": { "description": "Problem details (RFC 9457), media type application/problem+json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No visible step of that session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No database is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Empty or too long note, or bad session id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "AgentApprovalOut": { "properties": { "required": { "type": "integer", "title": "Required" }, "approvals": { "type": "integer", "title": "Approvals" }, "satisfied": { "type": "boolean", "title": "Satisfied" } }, "type": "object", "required": [ "required", "approvals", "satisfied" ], "title": "AgentApprovalOut" }, "AgentAttemptOut": { "properties": { "id": { "type": "string", "title": "Id" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "open_conflicts": { "type": "integer", "title": "Open Conflicts" }, "resolved_conflicts": { "type": "integer", "title": "Resolved Conflicts" }, "counts": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "type": "object", "title": "Counts" } }, "type": "object", "required": [ "id", "result", "open_conflicts", "resolved_conflicts", "counts" ], "title": "AgentAttemptOut", "description": "The merge attempt: Conflicts between the task branch and the target." }, "AgentMergeOut": { "properties": { "requested": { "type": "boolean", "title": "Requested" }, "allowed": { "type": "boolean", "title": "Allowed", "description": "The Domain allows automatic merges for the caller's role." }, "performed": { "type": "boolean", "title": "Performed" }, "blockers": { "items": { "type": "string" }, "type": "array", "title": "Blockers", "description": "What keeps the Proposal from merging by itself: `approvals-pending` (the target needs approvals), `review-policy-needs-approval` (the Operation's review policy asks for a review and nobody approved)." } }, "type": "object", "required": [ "requested", "allowed", "performed", "blockers" ], "title": "AgentMergeOut" }, "AgentWriteOut": { "properties": { "status": { "type": "string", "enum": [ "proposed", "merged", "conflicts" ], "title": "Status" }, "operation": { "type": "string", "title": "Operation" }, "branch": { "type": "string", "title": "Branch", "description": "The task branch." }, "target": { "type": "string", "title": "Target", "description": "The branch the Proposal merges into." }, "invocation_id": { "type": "string", "title": "Invocation Id" }, "parameters_hash": { "type": "string", "title": "Parameters Hash" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Last Revision written on the task branch." }, "revisions": { "items": { "type": "string" }, "type": "array", "title": "Revisions" }, "edit_count": { "type": "integer", "title": "Edit Count" }, "replayed": { "type": "boolean", "title": "Replayed" }, "proposal": { "$ref": "#/components/schemas/ProposalRefOut" }, "approval": { "$ref": "#/components/schemas/AgentApprovalOut" }, "attempt": { "anyOf": [ { "$ref": "#/components/schemas/AgentAttemptOut" }, { "type": "null" } ] }, "merge": { "$ref": "#/components/schemas/AgentMergeOut" }, "merged_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merged Revision", "description": "Head of the target after an automatic merge." }, "branch_created": { "type": "boolean", "title": "Branch Created" }, "branch_deleted": { "type": "boolean", "title": "Branch Deleted" }, "warnings": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Warnings" }, "next": { "items": { "$ref": "#/components/schemas/NextHint" }, "type": "array", "title": "Next" } }, "type": "object", "required": [ "status", "operation", "branch", "target", "invocation_id", "parameters_hash", "revision", "revisions", "edit_count", "replayed", "proposal", "approval", "attempt", "merge", "merged_revision", "branch_created", "branch_deleted", "warnings", "next" ], "title": "AgentWriteOut", "description": "An Operation that needed review, run on a task branch and proposed." }, "Aggregate": { "properties": { "group_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group By" } }, "additionalProperties": false, "type": "object", "title": "Aggregate", "description": "Count the matching Records per Kind, and per value of `group_by` when given." }, "AggregateCount": { "properties": { "kind": { "type": "string", "title": "Kind" }, "value": { "$ref": "#/components/schemas/JsonValue", "description": "Group value when `group_by` is given." }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "kind", "count" ], "title": "AggregateCount" }, "AggregateOut": { "properties": { "counts": { "items": { "$ref": "#/components/schemas/AggregateCount" }, "type": "array", "title": "Counts" }, "truncated": { "type": "boolean", "title": "Truncated", "default": false } }, "type": "object", "required": [ "counts" ], "title": "AggregateOut" }, "AllOf": { "properties": { "and": { "items": { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, "type": "array", "minItems": 1, "title": "And" } }, "additionalProperties": false, "type": "object", "required": [ "and" ], "title": "AllOf" }, "AnyOf": { "properties": { "or": { "items": { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, "type": "array", "minItems": 1, "title": "Or" } }, "additionalProperties": false, "type": "object", "required": [ "or" ], "title": "AnyOf" }, "ApiKeyCreated": { "properties": { "id": { "type": "string", "title": "Id" }, "principal_id": { "type": "string", "title": "Principal Id" }, "prefix": { "type": "string", "title": "Prefix" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "allowed_networks": { "items": { "type": "string" }, "type": "array", "title": "Allowed Networks", "description": "Client networks (CIDR) the key may be used from; empty: any address." }, "key": { "type": "string", "title": "Key" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "Role granted to the new service principal in the Domain." } }, "type": "object", "required": [ "id", "principal_id", "prefix", "scopes", "expires_at", "last_used_at", "revoked_at", "created_at", "key" ], "title": "ApiKeyCreated", "description": "A new API key; `key` is the only time the secret is returned." }, "ApiKeyOut": { "properties": { "id": { "type": "string", "title": "Id" }, "principal_id": { "type": "string", "title": "Principal Id" }, "prefix": { "type": "string", "title": "Prefix" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "allowed_networks": { "items": { "type": "string" }, "type": "array", "title": "Allowed Networks", "description": "Client networks (CIDR) the key may be used from; empty: any address." } }, "type": "object", "required": [ "id", "principal_id", "prefix", "scopes", "expires_at", "last_used_at", "revoked_at", "created_at" ], "title": "ApiKeyOut", "description": "An API key. The secret is never shown again after creation." }, "ApprovalOut": { "properties": { "protected": { "type": "boolean", "title": "Protected" }, "required": { "type": "integer", "title": "Required" }, "approvals": { "type": "integer", "title": "Approvals" }, "approvers": { "items": { "type": "string" }, "type": "array", "title": "Approvers" }, "changes_requested": { "items": { "type": "string" }, "type": "array", "title": "Changes Requested" }, "satisfied": { "type": "boolean", "title": "Satisfied" }, "required_from_stewards": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Required From Stewards", "description": "Approvals that must come from the Proposal's assignees (protection rule required_approvals_from_stewards); null when the rule does not apply." }, "steward_approvals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Steward Approvals", "description": "Approvals given by assignees, when the rule applies." }, "stewards_unavailable": { "type": "boolean", "title": "Stewards Unavailable", "description": "Steward roles are declared but fewer principals can approve than the rule requires (merge refused with stewards-unavailable).", "default": false }, "required_roles": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Required Roles", "description": "Roles that must each have approved (protection rule required_roles); null when the rule does not apply." }, "missing_roles": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Missing Roles", "description": "Required roles without a counted approval yet, when the rule applies." } }, "type": "object", "required": [ "protected", "required", "approvals", "approvers", "changes_requested", "satisfied" ], "title": "ApprovalOut", "description": "Review state against the target branch's protection." }, "AttemptOut": { "properties": { "id": { "type": "string", "title": "Id" }, "proposal": { "type": "string", "title": "Proposal" }, "status": { "type": "string", "title": "Status" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result", "description": "`conflicts`, `merged`, `fast_forward` or `up_to_date`." }, "base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base" }, "ours": { "type": "string", "title": "Ours" }, "theirs": { "type": "string", "title": "Theirs" }, "virtual_base": { "type": "boolean", "title": "Virtual Base" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Target head after the merge committed." }, "policy": { "additionalProperties": true, "type": "object", "title": "Policy" }, "open_conflicts": { "type": "integer", "title": "Open Conflicts" }, "resolved_conflicts": { "type": "integer", "title": "Resolved Conflicts" }, "counts": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "type": "object", "title": "Counts", "description": "Per Conflict code: open, resolved." }, "recomputed": { "type": "boolean", "title": "Recomputed", "description": "This request ran the merge." }, "stale": { "type": "boolean", "title": "Stale", "description": "A head moved since the previous attempt." }, "resolutions": { "items": { "$ref": "#/components/schemas/ResolutionOut" }, "type": "array", "title": "Resolutions" }, "unmatched_resolutions": { "items": { "type": "string" }, "type": "array", "title": "Unmatched Resolutions" }, "auto_resolutions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Auto Resolutions" } }, "type": "object", "required": [ "id", "proposal", "status", "result", "base", "ours", "theirs", "virtual_base", "created_at", "created_by", "revision", "policy", "open_conflicts", "resolved_conflicts", "counts", "recomputed", "stale", "resolutions", "unmatched_resolutions", "auto_resolutions" ], "title": "AttemptOut", "description": "A merge attempt (design 6.8 step 5) and the resolutions of its Proposal." }, "AttributeChangeOut": { "properties": { "name": { "type": "string", "title": "Name", "description": "Attribute api name." }, "before": { "$ref": "#/components/schemas/JsonValue", "description": "Value before; with `values=true`." }, "after": { "$ref": "#/components/schemas/JsonValue", "description": "Value after; with `values=true`." }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ProvenanceOut" }, { "type": "null" } ] } }, "type": "object", "required": [ "name" ], "title": "AttributeChangeOut" }, "AttributeCondition": { "properties": { "attr": { "type": "string", "minLength": 1, "title": "Attr" }, "op": { "$ref": "#/components/schemas/Operator" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "additionalProperties": false, "type": "object", "required": [ "attr", "op" ], "title": "AttributeCondition", "description": "Compare an Attribute, `key` or `title` with a value." }, "AttributeCoverage": { "properties": { "kind": { "type": "string", "title": "Kind" }, "attribute": { "type": "string", "title": "Attribute" }, "missing": { "type": "number", "title": "Missing", "description": "Share of the Kind's Records without a value, 0 to 1." }, "missing_records": { "type": "integer", "title": "Missing Records", "description": "Records without a value (estimated if sampled)." }, "used_in": { "items": { "type": "string", "enum": [ "where", "select", "order_by", "resolve" ] }, "type": "array", "title": "Used In", "description": "Where the request used the Attribute (resolve: a candidate named it)." } }, "type": "object", "required": [ "kind", "attribute", "missing", "missing_records", "used_in" ], "title": "AttributeCoverage", "description": "How many Records of a Kind miss an Attribute the request used." }, "AttributeLineageOut": { "properties": { "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "origin_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Type", "description": "Provenance origin type." }, "origin": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Origin", "description": "Provenance origin." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Message of the Revision." }, "name": { "type": "string", "title": "Name" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "type": "object", "required": [ "name" ], "title": "AttributeLineageOut" }, "AuditBreakOut": { "properties": { "seq": { "type": "integer", "title": "Seq" }, "reason": { "type": "string", "title": "Reason", "description": "`chain link broken` (an entry was removed, reordered or inserted) or `entry content changed` (an entry was edited)." } }, "type": "object", "required": [ "seq", "reason" ], "title": "AuditBreakOut", "description": "The first audit entry of a chain that does not verify." }, "AuditEntryOut": { "properties": { "seq": { "type": "integer", "title": "Seq" }, "at": { "type": "string", "format": "date-time", "title": "At" }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id" }, "actor": { "type": "string", "title": "Actor" }, "action": { "type": "string", "title": "Action" }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target" }, "details": { "additionalProperties": true, "type": "object", "title": "Details" }, "entry_hash": { "type": "string", "title": "Entry Hash" } }, "type": "object", "required": [ "seq", "at", "domain_id", "actor", "action", "target", "details", "entry_hash" ], "title": "AuditEntryOut", "description": "An audit log entry." }, "AuditVerificationOut": { "properties": { "domain_id": { "type": "string", "title": "Domain Id" }, "intact": { "type": "boolean", "title": "Intact", "description": "Every entry in the range verified." }, "checked": { "type": "integer", "title": "Checked", "description": "Entries that verified, before the first broken one." }, "after_seq": { "type": "integer", "title": "After Seq", "description": "Entries up to this `seq` were not read." }, "last_seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Seq", "description": "`seq` of the last entry that verified; pass it as `after_seq` later to verify only what was appended since." }, "first_broken": { "anyOf": [ { "$ref": "#/components/schemas/AuditBreakOut" }, { "type": "null" } ] } }, "type": "object", "required": [ "domain_id", "intact", "checked", "after_seq", "last_seq" ], "title": "AuditVerificationOut", "description": "Result of recomputing a Domain's audit chain." }, "BranchCreate": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Branch or tag to start from; default: the default branch." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Revision id to start at; default: the head of `source`." }, "mode": { "anyOf": [ { "$ref": "#/components/schemas/BranchMode" }, { "type": "null" } ], "description": "`copy`: the branch gets its own materialized rows. `overlay`: it stores only the rows it changes and reads the rest from `source` as of its head (only when starting at the head of a fully materialized branch; otherwise a copy). Default: `store.materialize.branch_mode`, overlay for names with an overlay prefix." } }, "type": "object", "required": [ "name" ], "title": "BranchCreate", "description": "A new branch, started at a Revision or at the head of a branch or tag." }, "BranchDetail": { "properties": { "name": { "type": "string", "title": "Name" }, "head": { "type": "string", "title": "Head" }, "protected": { "type": "boolean", "title": "Protected" }, "default": { "type": "boolean", "title": "Default" }, "materialization": { "$ref": "#/components/schemas/Materialization" }, "version": { "type": "integer", "title": "Version" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "materialization_status": { "anyOf": [ { "$ref": "#/components/schemas/MaterializationStatus" }, { "type": "null" } ], "description": "Background copy of the branch: a large copy branch is created as an overlay of its source (`materialization` is `overlay`, reads and writes work at once) and a job copies its rows in batches; a large copy that cannot start as an overlay (of an overlay, from an older Revision) is `building` until a job writes its rows from its tree (its head reads like a past Revision, commits answer 409). `pending` (queued, or waiting for a retry), `running`, `done` (`materialization` is then `full`) or `failed` (a build that failed for good). Null for a branch that was never copied in the background." }, "materialization_progress": { "anyOf": [ { "$ref": "#/components/schemas/MaterializationProgress" }, { "type": "null" } ], "description": "Progress of the background copy; null without one." }, "ahead": { "type": "integer", "title": "Ahead", "description": "Revisions on this branch that the default branch lacks." }, "behind": { "type": "integer", "title": "Behind", "description": "Revisions on the default branch that this branch lacks." } }, "type": "object", "required": [ "name", "head", "protected", "default", "materialization", "version", "created_at", "created_by", "ahead", "behind" ], "title": "BranchDetail", "description": "A branch with its distance to the default branch." }, "BranchMode": { "type": "string", "enum": [ "copy", "overlay" ], "title": "BranchMode", "description": "The materialization a caller asks for when creating a branch." }, "BranchOut": { "properties": { "name": { "type": "string", "title": "Name" }, "head": { "type": "string", "title": "Head" }, "protected": { "type": "boolean", "title": "Protected" }, "default": { "type": "boolean", "title": "Default" }, "materialization": { "$ref": "#/components/schemas/Materialization" }, "version": { "type": "integer", "title": "Version" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "materialization_status": { "anyOf": [ { "$ref": "#/components/schemas/MaterializationStatus" }, { "type": "null" } ], "description": "Background copy of the branch: a large copy branch is created as an overlay of its source (`materialization` is `overlay`, reads and writes work at once) and a job copies its rows in batches; a large copy that cannot start as an overlay (of an overlay, from an older Revision) is `building` until a job writes its rows from its tree (its head reads like a past Revision, commits answer 409). `pending` (queued, or waiting for a retry), `running`, `done` (`materialization` is then `full`) or `failed` (a build that failed for good). Null for a branch that was never copied in the background." }, "materialization_progress": { "anyOf": [ { "$ref": "#/components/schemas/MaterializationProgress" }, { "type": "null" } ], "description": "Progress of the background copy; null without one." } }, "type": "object", "required": [ "name", "head", "protected", "default", "materialization", "version", "created_at", "created_by" ], "title": "BranchOut", "description": "A branch." }, "BranchUpdate": { "properties": { "protected": { "type": "boolean", "title": "Protected", "description": "Protected branches accept changes only through Proposals (design 6.5)." } }, "type": "object", "required": [ "protected" ], "title": "BranchUpdate", "description": "Branch flags." }, "BudgetOut": { "properties": { "limit_tokens": { "type": "integer", "title": "Limit Tokens" }, "used_tokens": { "type": "integer", "title": "Used Tokens", "description": "Estimated tokens of the sections." }, "chars_per_token": { "type": "number", "title": "Chars Per Token" }, "sections": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Sections", "description": "Estimated tokens per section." }, "trimmed": { "items": { "$ref": "#/components/schemas/TrimOut" }, "type": "array", "title": "Trimmed" }, "omitted": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Omitted", "description": "Entries removed to fit, per section." }, "over_budget": { "type": "boolean", "title": "Over Budget", "description": "True when even the seed Records exceed the budget." }, "capped": { "type": "boolean", "title": "Capped", "description": "True when graph caps cut the neighborhood, or a depth or budget of the lens was served at the configured cap." } }, "type": "object", "required": [ "limit_tokens", "used_tokens", "chars_per_token", "sections", "trimmed", "omitted", "over_budget", "capped" ], "title": "BudgetOut" }, "CandidateStatus": { "type": "string", "enum": [ "open", "resolved", "dismissed", "obsolete" ], "title": "CandidateStatus", "description": "``open`` until a person decides; only the pipeline sets ``obsolete`` (AC-33)." }, "CandidateType": { "type": "string", "enum": [ "duplicate", "contradiction", "superseded", "stale" ], "title": "CandidateType" }, "ChangeKind": { "type": "string", "enum": [ "created", "updated", "deleted" ], "title": "ChangeKind" }, "ChangeOut": { "properties": { "element": { "$ref": "#/components/schemas/PartitionType" }, "change": { "$ref": "#/components/schemas/ChangeType" }, "partition": { "type": "string", "title": "Partition" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "relation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relation" }, "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key", "description": "Record key or schema element id." }, "from_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Key" }, "to_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Key" }, "element_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Element Type", "description": "Schema object type." }, "api_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Name" }, "old_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Old Hash" }, "new_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Hash" }, "changes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ValueChange" }, "type": "array" }, { "type": "null" } ], "title": "Changes" }, "provenance": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Provenance entry per changed Attribute (changesets)." } }, "type": "object", "required": [ "element", "change", "partition" ], "title": "ChangeOut", "description": "One changed element." }, "ChangeType": { "type": "string", "enum": [ "added", "removed", "modified" ], "title": "ChangeType" }, "ChangesFeedPage": { "properties": { "branch": { "type": "string", "title": "Branch" }, "head": { "type": "string", "title": "Head" }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Since" }, "items": { "items": { "$ref": "#/components/schemas/RevisionEventOut" }, "type": "array", "title": "Items" }, "next_since": { "type": "string", "title": "Next Since", "description": "Pass as `since` to continue." }, "more": { "type": "boolean", "title": "More", "description": "True when more Revisions follow `next_since`." } }, "type": "object", "required": [ "branch", "head", "items", "next_since", "more" ], "title": "ChangesFeedPage" }, "ChangesPage": { "properties": { "from_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Revision", "description": "Older side; null for a root Revision." }, "to_revision": { "type": "string", "title": "To Revision" }, "total": { "type": "integer", "title": "Total" }, "summary": { "items": { "$ref": "#/components/schemas/PartitionSummary" }, "type": "array", "title": "Summary" }, "items": { "items": { "$ref": "#/components/schemas/ChangeOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "from_revision", "to_revision", "total", "summary", "items" ], "title": "ChangesPage", "description": "A page of element changes with the summary of all of them." }, "CheckOut": { "properties": { "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "enum": [ "passed", "failed", "pending" ], "title": "Status" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "candidates": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Candidates", "description": "`reconciliation`: ids of the first open candidates of the Proposal." } }, "type": "object", "required": [ "name", "status" ], "title": "CheckOut", "description": "One Proposal check (design 10.3)." }, "CheckReport": { "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "not_configured", "failed" ], "title": "Status" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "status" ], "title": "CheckReport", "description": "Outcome of one dependency check." }, "ConflictOut": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "enum": [ "open", "resolved" ], "title": "Status" }, "resolution": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Resolution" } }, "additionalProperties": true, "type": "object", "required": [ "id", "status" ], "title": "ConflictOut", "description": "A Conflict (core `Conflict`) with its id, state and members." }, "ConflictsOut": { "properties": { "id": { "type": "string", "title": "Id" }, "proposal": { "type": "string", "title": "Proposal" }, "status": { "type": "string", "title": "Status" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result", "description": "`conflicts`, `merged`, `fast_forward` or `up_to_date`." }, "base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base" }, "ours": { "type": "string", "title": "Ours" }, "theirs": { "type": "string", "title": "Theirs" }, "virtual_base": { "type": "boolean", "title": "Virtual Base" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Target head after the merge committed." }, "policy": { "additionalProperties": true, "type": "object", "title": "Policy" }, "open_conflicts": { "type": "integer", "title": "Open Conflicts" }, "resolved_conflicts": { "type": "integer", "title": "Resolved Conflicts" }, "counts": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "type": "object", "title": "Counts", "description": "Per Conflict code: open, resolved." }, "recomputed": { "type": "boolean", "title": "Recomputed", "description": "This request ran the merge." }, "stale": { "type": "boolean", "title": "Stale", "description": "A head moved since the previous attempt." }, "resolutions": { "items": { "$ref": "#/components/schemas/ResolutionOut" }, "type": "array", "title": "Resolutions" }, "unmatched_resolutions": { "items": { "type": "string" }, "type": "array", "title": "Unmatched Resolutions" }, "auto_resolutions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Auto Resolutions" }, "conflicts": { "items": { "$ref": "#/components/schemas/ConflictOut" }, "type": "array", "title": "Conflicts" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "id", "proposal", "status", "result", "base", "ours", "theirs", "virtual_base", "created_at", "created_by", "revision", "policy", "open_conflicts", "resolved_conflicts", "counts", "recomputed", "stale", "resolutions", "unmatched_resolutions", "auto_resolutions", "conflicts" ], "title": "ConflictsOut", "description": "An attempt with one page of its Conflicts." }, "ContextPackOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "revision": { "type": "string", "title": "Revision" }, "etag": { "type": "string", "title": "Etag" }, "seeds": { "items": { "$ref": "#/components/schemas/PackRecordOut" }, "type": "array", "title": "Seeds" }, "neighbors": { "items": { "$ref": "#/components/schemas/PackNeighborOut" }, "type": "array", "title": "Neighbors" }, "links": { "additionalProperties": { "items": { "$ref": "#/components/schemas/PackLinkOut" }, "type": "array" }, "type": "object", "title": "Links" }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/SchemaFragmentOut" }, { "type": "null" } ] }, "recent_changes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PackChangeOut" }, "type": "array" }, { "type": "null" } ], "title": "Recent Changes" }, "lineage": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PackLineageOut" }, "type": "array" }, { "type": "null" } ], "title": "Lineage" }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Since" }, "budget": { "$ref": "#/components/schemas/BudgetOut" } }, "type": "object", "required": [ "domain", "branch", "revision", "etag", "seeds", "neighbors", "links", "budget" ], "title": "ContextPackOut", "description": "A context pack in JSON (`format: json`)." }, "ContextRequest": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the Domain's default branch." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel, served from a snapshot)." }, "refs": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Refs", "description": "Seed Records as `Kind/key` references." }, "query": { "anyOf": [ { "$ref": "#/components/schemas/Query" }, { "type": "null" } ], "description": "DSL query selecting the seeds." }, "search": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Search", "description": "Lexical search text selecting the seeds." }, "budget_tokens": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Budget Tokens", "description": "Estimated token budget; default from settings." }, "depth": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Depth", "description": "Neighborhood depth (0: none)." }, "relations": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relations", "description": "Relation api names to follow (forward or inverse); default: all, or the Relations of `lens`." }, "traits": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Traits", "description": "Trait api names: with `search` or `query` seeds, only Records of the Kinds implementing them (that the caller may read) become seeds, and only Records of those Kinds are neighbors. Seeds named by `refs` are always kept." }, "lens": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lens", "description": "Lens api name (a read preset of the schema): its Relations, depth, sections and budget are the defaults of this request, its Kinds and Traits limit neighbors and `search` and `query` seeds like `traits`. Members given here win." }, "include_schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Schema", "description": "Default: the lens's, else true." }, "include_recent_changes": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Recent Changes", "description": "Default: the lens's, else true." }, "include_lineage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Lineage", "description": "Default: the lens's, else true." }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Since", "description": "Revision id or tag: recent changes after it; default: the latest changes." }, "format": { "type": "string", "enum": [ "json", "markdown" ], "title": "Format", "description": "`markdown` answers text/markdown to paste into a prompt.", "default": "json" } }, "additionalProperties": false, "type": "object", "title": "ContextRequest", "description": "What an agent needs to reason about: seed Records and how much around them." }, "CountCondition": { "properties": { "count": { "type": "string", "minLength": 1, "title": "Count" }, "op": { "$ref": "#/components/schemas/Operator" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where" } }, "additionalProperties": false, "type": "object", "required": [ "count", "op", "value" ], "title": "CountCondition", "description": "Compare the number of Links of `count` (to Records matching `where`) with a value." }, "CountsResponse": { "properties": { "revision": { "type": "string", "title": "Revision" }, "partitions": { "items": { "$ref": "#/components/schemas/PartitionCount" }, "type": "array", "title": "Partitions" } }, "type": "object", "required": [ "revision", "partitions" ], "title": "CountsResponse" }, "CoverageOut": { "properties": { "kinds": { "items": { "$ref": "#/components/schemas/KindCoverage" }, "type": "array", "title": "Kinds" }, "attributes": { "items": { "$ref": "#/components/schemas/AttributeCoverage" }, "type": "array", "title": "Attributes" }, "sources": { "items": { "$ref": "#/components/schemas/SourceFreshness" }, "type": "array", "title": "Sources" }, "unknown": { "items": { "type": "string" }, "type": "array", "title": "Unknown", "description": "Resolution: phrases that matched nothing the caller can read in this Domain (no Kind, Attribute or indexed value)." }, "notes": { "items": { "type": "string" }, "type": "array", "title": "Notes", "description": "One line per signal, for agents and people." }, "omitted": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Omitted", "description": "Why statistics are left out (e.g. not the default branch)." } }, "type": "object", "title": "CoverageOut", "description": "How complete an answer can be (design 8.11): an empty result is not missing data. Read\nfrom statistics of the default branch head, never from the Records; only Kinds and\nAttributes the caller may read are described." }, "CreateApiKey": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Name of the service principal." }, "role": { "type": "string", "title": "Role", "description": "Role granted in this Domain to the new service principal.", "default": "agent-reader" }, "ttl_days": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Ttl Days", "description": "Lifetime in days; the configured default when omitted." }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id", "description": "Add the key to an existing service principal instead of creating one; its grants are left as they are. The principal must hold a grant in this Domain and must not be an installation administrator." }, "allowed_networks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Networks", "description": "Client networks the key may be used from, e.g. 203.0.113.0/24 or 2001:db8::/48; a single address is a network of one. Requests from other addresses are refused as if the key were invalid. Empty or omitted: any address. At most `keeper.auth.api_keys.max_allowed_networks` entries." } }, "type": "object", "required": [ "name" ], "title": "CreateApiKey", "description": "Request to create an API key for a Domain." }, "CreateGrant": { "properties": { "subject": { "type": "string", "minLength": 1, "title": "Subject", "description": "Principal or group id." }, "role": { "type": "string", "title": "Role" }, "scope_type": { "$ref": "#/components/schemas/GrantScope", "default": "domain" }, "scope_ref": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Scope Ref", "description": "Kind api name, Operation name or branch pattern; required unless the scope is the whole Domain." } }, "type": "object", "required": [ "subject", "role" ], "title": "CreateGrant", "description": "Request to grant a role." }, "CreateWebhook": { "properties": { "url": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Url", "description": "Target of the POST requests." }, "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Events", "description": "Event types delivered: revision.committed, operation., or operation.* for every Operation event; default: revision.committed and operation.*." }, "branches": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Branches", "description": "Only events of these branches; default: all." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description" }, "clearances": { "items": { "type": "string", "enum": [ "pii", "confidential", "restricted" ] }, "type": "array", "title": "Clearances", "description": "Sensitivity tags whose values the webhook receives in clear; others are masked. Each needs the matching clearance permission on the Domain." } }, "additionalProperties": false, "type": "object", "required": [ "url" ], "title": "CreateWebhook" }, "CreatedOut": { "properties": { "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "origin_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Type", "description": "Provenance origin type." }, "origin": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Origin", "description": "Provenance origin." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Message of the Revision." }, "revision_origin": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Revision Origin", "description": "Origin of the Revision (`type`, `ref`)." } }, "type": "object", "title": "CreatedOut" }, "DecideIn": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/ItemDecisionIn" }, "type": "array", "title": "Decisions" }, "where": { "anyOf": [ { "$ref": "#/components/schemas/ItemSelection" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, { "type": "null" } ], "title": "Decision", "description": "Decision for `where`." } }, "additionalProperties": false, "type": "object", "title": "DecideIn", "description": "Decisions by item, and or one decision for every item matching `where`." }, "DecideOut": { "properties": { "proposal_id": { "type": "string", "title": "Proposal Id" }, "title": { "type": "string", "title": "Title" }, "checks": { "additionalProperties": true, "type": "object", "title": "Checks", "description": "The `extraction` summary and `merge` preview." }, "items": { "items": { "$ref": "#/components/schemas/ItemOut" }, "type": "array", "title": "Items", "description": "The decided items." }, "materialized": { "$ref": "#/components/schemas/MaterializedOut" } }, "type": "object", "required": [ "proposal_id", "title", "checks", "items", "materialized" ], "title": "DecideOut" }, "DecideSuggestionsIn": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/SuggestionDecisionIn" }, "type": "array", "minItems": 1, "title": "Decisions" } }, "additionalProperties": false, "type": "object", "required": [ "decisions" ], "title": "DecideSuggestionsIn" }, "DecideSuggestionsOut": { "properties": { "suggestions": { "items": { "$ref": "#/components/schemas/SuggestionOut" }, "type": "array", "title": "Suggestions" }, "proposal": { "anyOf": [ { "$ref": "#/components/schemas/SuggestionProposalOut" }, { "type": "null" } ], "description": "The Proposal opened for the accepted suggestions." } }, "type": "object", "required": [ "suggestions" ], "title": "DecideSuggestionsOut" }, "DerivationPreviewOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "revision": { "type": "string", "title": "Revision", "description": "Revision whose Records were evaluated." }, "served_from": { "type": "string", "title": "Served From" }, "derivation": { "type": "string", "title": "Derivation" }, "kind": { "type": "string", "title": "Kind" }, "attribute": { "type": "string", "title": "Attribute" }, "items": { "items": { "$ref": "#/components/schemas/PreviewItemOut" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "domain", "branch", "revision", "served_from", "derivation", "kind", "attribute", "items" ], "title": "DerivationPreviewOut", "description": "Values a candidate Derivation computes on sample Records." }, "DerivationPreviewRequest": { "properties": { "yaml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yaml", "description": "Full schema document; elements it leaves out are removed." }, "patch": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Patch", "description": "Partial document (same layout as the YAML document): each element replaces the element with the same api name, or is added." }, "remove": { "items": { "$ref": "#/components/schemas/ElementRemoval" }, "type": "array", "title": "Remove" }, "derivation": { "type": "string", "minLength": 1, "title": "Derivation", "description": "Api name of the `expression` or `aggregate` Derivation to evaluate in the schema the change set produces." }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the default branch." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id, tag or branch name; only the branch head." }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Limit", "description": "Records to evaluate; default and maximum: `read.derivation_preview`." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Keys", "description": "Keys of the Records to evaluate instead of the first ones by key; at most `read.derivation_preview.max_limit`, each at most `read.derivation_preview_max_key_length` characters." } }, "type": "object", "required": [ "derivation" ], "title": "DerivationPreviewRequest", "description": "A candidate schema change set and the Derivation to evaluate in it." }, "DerivedCondition": { "properties": { "derived": { "type": "string", "minLength": 1, "title": "Derived" }, "op": { "$ref": "#/components/schemas/Operator" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "additionalProperties": false, "type": "object", "required": [ "derived", "op" ], "title": "DerivedCondition", "description": "Compare a derived Attribute with a value." }, "DerivedReport": { "properties": { "attributes": { "items": { "type": "string" }, "type": "array", "title": "Attributes" }, "records_missing_value": { "type": "integer", "title": "Records Missing Value" }, "stale": { "type": "boolean", "title": "Stale" } }, "type": "object", "required": [ "attributes", "records_missing_value", "stale" ], "title": "DerivedReport", "description": "Derived Attributes whose materialized value is missing, so reads cannot serve it.\n\nOnly presence is checked: values are not recomputed and compared with the stored ones\n(`lorebase_store.materialize.verify` with `derived=True` does that)." }, "DocumentDetailOut": { "properties": { "id": { "type": "string", "title": "Id" }, "filename": { "type": "string", "title": "Filename" }, "media_type": { "type": "string", "title": "Media Type" }, "sha256": { "type": "string", "title": "Sha256" }, "size": { "type": "integer", "title": "Size" }, "text_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text Sha256", "description": "Set once Scribe parsed the text." }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "source_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Key", "description": "Stable identity; null: keyless." }, "version": { "type": "integer", "title": "Version", "description": "1 for keyless documents and the first version of a key." }, "replaces": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaces", "description": "The version this one replaced." }, "status": { "type": "string", "enum": [ "active", "superseded", "retired", "purged" ], "title": "Status" }, "retired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Retired At" }, "retired_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retired By" }, "purged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Purged At" }, "purged_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purged By" }, "extraction_jobs": { "items": { "$ref": "#/components/schemas/ExtractionJobOut" }, "type": "array", "title": "Extraction Jobs", "description": "Newest first." }, "open_stale_candidates": { "type": "integer", "title": "Open Stale Candidates", "description": "Open `stale` reconciliation candidates whose claims come from this document (its evidence gone from a newer version, or the document retired)." }, "can_retire": { "type": "boolean", "title": "Can Retire", "description": "The caller holds `document.retire` Domain-wide." }, "can_purge": { "type": "boolean", "title": "Can Purge", "description": "The caller holds `document.purge` Domain-wide." } }, "type": "object", "required": [ "id", "filename", "media_type", "sha256", "size", "metadata", "created_by", "version", "status", "extraction_jobs", "open_stale_candidates", "can_retire", "can_purge" ], "title": "DocumentDetailOut" }, "DocumentOut": { "properties": { "id": { "type": "string", "title": "Id" }, "filename": { "type": "string", "title": "Filename" }, "media_type": { "type": "string", "title": "Media Type" }, "sha256": { "type": "string", "title": "Sha256" }, "size": { "type": "integer", "title": "Size" }, "text_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text Sha256", "description": "Set once Scribe parsed the text." }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "source_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Key", "description": "Stable identity; null: keyless." }, "version": { "type": "integer", "title": "Version", "description": "1 for keyless documents and the first version of a key." }, "replaces": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaces", "description": "The version this one replaced." }, "status": { "type": "string", "enum": [ "active", "superseded", "retired", "purged" ], "title": "Status" }, "retired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Retired At" }, "retired_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retired By" }, "purged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Purged At" }, "purged_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Purged By" } }, "type": "object", "required": [ "id", "filename", "media_type", "sha256", "size", "metadata", "created_by", "version", "status" ], "title": "DocumentOut" }, "DocumentPurged": { "properties": { "document": { "$ref": "#/components/schemas/DocumentOut" }, "job_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Job Id", "description": "Queued evidence check of the retirement, if this purge retired the document." }, "blob_deleted": { "type": "boolean", "title": "Blob Deleted", "description": "The bytes were deleted (no other document holds them)." }, "text_deleted": { "type": "boolean", "title": "Text Deleted", "description": "The parsed text was deleted." }, "chunks": { "type": "integer", "title": "Chunks", "description": "Chunks deleted." }, "cache_entries": { "type": "integer", "title": "Cache Entries", "description": "Cached model answers of its chunks deleted." }, "items": { "type": "integer", "title": "Items", "description": "Proposal items whose evidence quotes were erased." }, "candidates": { "type": "integer", "title": "Candidates", "description": "Reconciliation candidates whose quotes were erased." }, "suggestions": { "type": "integer", "title": "Suggestions", "description": "Schema suggestions whose example quotes were erased." } }, "type": "object", "required": [ "document", "blob_deleted", "text_deleted", "chunks", "cache_entries", "items", "candidates", "suggestions" ], "title": "DocumentPurged" }, "DocumentRetired": { "properties": { "document": { "$ref": "#/components/schemas/DocumentOut" }, "job_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Job Id", "description": "Queued evidence check; null when it was retired before." } }, "type": "object", "required": [ "document" ], "title": "DocumentRetired" }, "DocumentTextOut": { "properties": { "document_id": { "type": "string", "title": "Document Id" }, "text_sha256": { "type": "string", "title": "Text Sha256", "description": "SHA-256 of the whole parsed text (UTF-8)." }, "text": { "type": "string", "title": "Text", "description": "The parsed text, cut at `keeper.documents.max_text_chars`." }, "length": { "type": "integer", "title": "Length", "description": "Characters (code points) of the whole parsed text." }, "truncated": { "type": "boolean", "title": "Truncated", "description": "`text` holds only the first characters." } }, "type": "object", "required": [ "document_id", "text_sha256", "text", "length", "truncated" ], "title": "DocumentTextOut" }, "DocumentUploaded": { "properties": { "document": { "$ref": "#/components/schemas/DocumentOut" }, "duplicate": { "type": "boolean", "title": "Duplicate", "description": "The same bytes were stored before." }, "job_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Job Id", "description": "Queued extraction job, if any." }, "check_job_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Check Job Id", "description": "Evidence check of a new version queued now (without extraction; with it, the extraction job queues the check once it finished)." } }, "type": "object", "required": [ "document", "duplicate" ], "title": "DocumentUploaded" }, "DomainCan": { "properties": { "settings": { "type": "boolean", "title": "Settings", "description": "The caller holds `domain.settings`: it may `PATCH` the Domain." } }, "type": "object", "required": [ "settings" ], "title": "DomainCan", "description": "What the caller may do with the Domain itself." }, "DomainCreate": { "properties": { "id": { "type": "string", "maxLength": 63, "pattern": "^[a-z][a-z0-9_-]*$", "title": "Id", "description": "Immutable slug." }, "display_name": { "type": "string", "maxLength": 200, "title": "Display Name", "default": "" }, "description": { "type": "string", "maxLength": 4000, "title": "Description", "default": "" }, "default_branch": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Default Branch", "default": "main" }, "settings": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Settings", "description": "Search language, materialization and merge policies." } }, "type": "object", "required": [ "id" ], "title": "DomainCreate", "description": "A new Domain." }, "DomainHealthOut": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "summary": { "$ref": "#/components/schemas/HealthSummary" }, "kinds": { "items": { "$ref": "#/components/schemas/KindHealth" }, "type": "array", "title": "Kinds" }, "relations": { "items": { "$ref": "#/components/schemas/RelationHealth" }, "type": "array", "title": "Relations" } }, "type": "object", "required": [ "revision", "served_from", "domain", "branch", "summary", "kinds", "relations" ], "title": "DomainHealthOut", "description": "Health of a Domain at the head of a branch, for the Kinds the caller may read." }, "DomainOut": { "properties": { "id": { "type": "string", "title": "Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "default_branch": { "type": "string", "title": "Default Branch" }, "settings": { "additionalProperties": true, "type": "object", "title": "Settings" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head", "description": "Head Revision of the default branch." }, "ignored_settings": { "items": { "type": "string" }, "type": "array", "title": "Ignored Settings", "description": "Paths of settings values that do not apply (invalid, or loosening a member the installation does not let Domains loosen), e.g. `extraction.mode`." }, "can": { "anyOf": [ { "$ref": "#/components/schemas/DomainCan" }, { "type": "null" } ], "description": "What the caller may do with the Domain; reported by `GET` and `PATCH` of one Domain, null in lists." } }, "type": "object", "required": [ "id", "display_name", "description", "default_branch", "settings", "created_at", "created_by", "head" ], "title": "DomainOut", "description": "A Domain and the head Revision of its default branch." }, "DomainUpdate": { "properties": { "display_name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Display Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "title": "Description" }, "settings": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Settings", "description": "Settings members to replace, `null` to remove one: `extraction` (`mode`: review_all, doubts_only or direct; `auto_accept_threshold`; `min_confidence`; `rules`: [{source_key_prefix, mode, auto_accept_threshold, min_confidence}])." } }, "type": "object", "title": "DomainUpdate", "description": "Display metadata and allowlisted settings members; omitted members are left\nunchanged." }, "DuplicateGroup": { "properties": { "attribute": { "type": "string", "title": "Attribute" }, "unique": { "type": "boolean", "title": "Unique", "description": "The Attribute is unique: this is a violation, not a hint." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "The normalized value; null for Attributes with sensitivity tags." }, "count": { "type": "integer", "title": "Count" }, "keys": { "items": { "type": "string" }, "type": "array", "title": "Keys" } }, "type": "object", "required": [ "attribute", "unique", "value", "count", "keys" ], "title": "DuplicateGroup", "description": "Records whose value of one Attribute is the same once case and spacing are ignored." }, "DuplicateOut": { "properties": { "section": { "type": "string", "enum": [ "kinds", "attributes", "relations" ], "title": "Section" }, "api_name": { "type": "string", "title": "Api Name" } }, "type": "object", "required": [ "section", "api_name" ], "title": "DuplicateOut" }, "DuplicateReport": { "properties": { "attributes": { "items": { "type": "string" }, "type": "array", "title": "Attributes", "description": "Attributes checked." }, "groups": { "items": { "$ref": "#/components/schemas/DuplicateGroup" }, "type": "array", "title": "Groups" }, "total_groups": { "type": "integer", "title": "Total Groups", "description": "Groups found, listed or not (`hidden` included)." }, "skipped": { "anyOf": [ { "type": "string", "enum": [ "too_many_records", "disabled" ] }, { "type": "null" } ], "title": "Skipped" }, "hidden": { "items": { "$ref": "#/components/schemas/HiddenDuplicates" }, "type": "array", "title": "Hidden", "description": "Attributes with duplicates whose groups are not listed: the caller is not cleared for their values." } }, "type": "object", "required": [ "attributes", "groups", "total_groups" ], "title": "DuplicateReport", "description": "Normalized exact duplicates on unique and title Attributes." }, "Edge": { "properties": { "relation": { "type": "string", "title": "Relation" }, "from": { "$ref": "#/components/schemas/RecordRef" }, "to": { "$ref": "#/components/schemas/RecordRef" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values" } }, "type": "object", "required": [ "relation", "from", "to", "values" ], "title": "Edge" }, "EdgeRef": { "properties": { "relation": { "type": "string", "title": "Relation" }, "from": { "$ref": "#/components/schemas/RecordRef" }, "to": { "$ref": "#/components/schemas/RecordRef" } }, "type": "object", "required": [ "relation", "from", "to" ], "title": "EdgeRef", "description": "A Link by its endpoints only (`values: false`)." }, "ElementChangeOut": { "properties": { "op": { "type": "string", "enum": [ "create", "update", "delete" ], "title": "Op" }, "section": { "type": "string", "title": "Section" }, "id": { "type": "string", "title": "Id" }, "api_name": { "type": "string", "title": "Api Name" } }, "type": "object", "required": [ "op", "section", "id", "api_name" ], "title": "ElementChangeOut", "description": "One element written or removed." }, "ElementRemoval": { "properties": { "section": { "type": "string", "enum": [ "kinds", "relations", "traits", "operations", "derivations", "sources", "lenses" ], "title": "Section" }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "Api name or id of the element." } }, "type": "object", "required": [ "section", "name" ], "title": "ElementRemoval", "description": "An element to remove." }, "EmbeddingOut": { "properties": { "model": { "type": "string", "title": "Model", "description": "Name the stored vectors are keyed by." }, "dims": { "type": "integer", "title": "Dims", "description": "Length of a query vector." } }, "type": "object", "required": [ "model", "dims" ], "title": "EmbeddingOut", "description": "The embedding model of a Domain: what a caller embeds `query_vector` with." }, "EraseIn": { "properties": { "kind": { "type": "string", "title": "Kind", "description": "Kind api name." }, "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key", "description": "Key of the Record whose values to erase." }, "attributes": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Attributes", "description": "With `key`: only these vault Attributes (api names); default: all." }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Vault Attribute (api name) whose `value` to erase." }, "value": { "$ref": "#/components/schemas/JsonValue", "description": "With `attribute`: the value to erase in every Record." }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Branch whose schema names Kinds and Attributes." } }, "type": "object", "required": [ "kind" ], "title": "EraseIn", "description": "Whose values to erase: a Record (`key`, optional `attributes`) or a value\n(`attribute` and `value`)." }, "EraseOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "kind": { "type": "string", "title": "Kind" }, "mode": { "type": "string", "enum": [ "record", "value" ], "title": "Mode" }, "erased": { "type": "integer", "title": "Erased", "description": "Vault values erased by this request." }, "unopenable": { "type": "integer", "title": "Unopenable", "description": "Rows looked at that are sealed under a key no longer configured: their fingerprints could not be made again, so a case variant among them may be missed.", "default": 0 } }, "type": "object", "required": [ "domain", "kind", "mode", "erased" ], "title": "EraseOut" }, "ExecuteRequest": { "properties": { "parameters": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Parameters" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the default branch." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Compute edits and violations without committing.", "default": false }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency Key", "description": "Same as the Idempotency-Key header; a retry with the same key and parameters returns the original result." }, "expected_head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Head", "description": "Fail with 409 unless the branch head is this Revision." }, "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Message" }, "task": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Task", "description": "Short slug naming the piece of work. When the Operation needs review (protected branch, review policy), Keeper runs it on the branch `agent/{principal}/{task}` and opens or updates a Proposal; without a task the refusal is the 409 `review-required`. Ignored when the Operation commits directly." }, "intent": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "title": "Intent", "description": "What the agent is after, in a sentence or two; becomes the start of the Proposal description." }, "auto_propose": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Propose", "description": "Open a Proposal when review is needed. Default: `keeper.agent_writes.auto_propose` for agent principals, false for others. `true` needs a `task`." }, "auto_merge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Merge", "description": "Merge the Proposal at once. Default: `keeper.agent_writes.auto_merge`. Honoured only when the Domain allows it for the caller's role, there is no open Conflict and the required approvals are in." } }, "type": "object", "title": "ExecuteRequest", "description": "An execution of an Operation." }, "ExecutionOut": { "properties": { "status": { "type": "string", "enum": [ "committed", "dry_run" ], "title": "Status" }, "operation": { "type": "string", "title": "Operation" }, "branch": { "type": "string", "title": "Branch" }, "invocation_id": { "type": "string", "title": "Invocation Id" }, "parameters_hash": { "type": "string", "title": "Parameters Hash" }, "head": { "type": "string", "title": "Head", "description": "Branch head the Operation ran against." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Last Revision written; null for dry runs." }, "revisions": { "items": { "type": "string" }, "type": "array", "title": "Revisions", "description": "Every Revision written (imports run in batches)." }, "edits": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Edits" }, "edit_count": { "type": "integer", "title": "Edit Count" }, "edits_truncated": { "type": "boolean", "title": "Edits Truncated" }, "violations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Violations" }, "violation_count": { "type": "integer", "title": "Violation Count" }, "warnings": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Warnings" }, "review_required": { "type": "boolean", "title": "Review Required", "description": "True when a non-dry run would need a Proposal on this branch." }, "replayed": { "type": "boolean", "title": "Replayed" } }, "type": "object", "required": [ "status", "operation", "branch", "invocation_id", "parameters_hash", "head", "revision", "revisions", "edits", "edit_count", "edits_truncated", "violations", "violation_count", "warnings", "review_required", "replayed" ], "title": "ExecutionOut", "description": "Result of an execution." }, "ExplainOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "revision": { "type": "string", "title": "Revision" }, "record": { "$ref": "#/components/schemas/ExplainedRecordOut" }, "created": { "anyOf": [ { "$ref": "#/components/schemas/CreatedOut" }, { "type": "null" } ] }, "attributes": { "items": { "$ref": "#/components/schemas/AttributeLineageOut" }, "type": "array", "title": "Attributes" }, "links": { "items": { "$ref": "#/components/schemas/LinkLineageOut" }, "type": "array", "title": "Links" }, "links_truncated": { "type": "boolean", "title": "Links Truncated" }, "history": { "$ref": "#/components/schemas/HistoryOut" }, "proposals": { "items": { "$ref": "#/components/schemas/lorebase_keeper__agents__explain__ProposalOut" }, "type": "array", "title": "Proposals" } }, "type": "object", "required": [ "domain", "branch", "revision", "record", "attributes", "links", "links_truncated", "history", "proposals" ], "title": "ExplainOut", "description": "An explained Record (`format: json`)." }, "ExplainedRecordOut": { "properties": { "ref": { "type": "string", "title": "Ref" }, "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values" }, "updated_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated Revision" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "ref", "kind", "key", "values" ], "title": "ExplainedRecordOut" }, "ExpressionCellOut": { "properties": { "value": { "$ref": "#/components/schemas/JsonValue", "description": "Null when there is none or `error` is set." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/PreviewErrorOut" }, { "type": "null" } ] } }, "type": "object", "required": [ "value" ], "title": "ExpressionCellOut", "description": "The value of one expression mapping for one row, before the transforms." }, "ExtractionEvidenceOut": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "document_id": { "type": "string", "title": "Document Id" }, "span_start": { "type": "integer", "title": "Span Start" }, "span_end": { "type": "integer", "title": "Span End" }, "model_id": { "type": "string", "title": "Model Id" }, "prompt_version": { "type": "string", "title": "Prompt Version" } }, "type": "object", "required": [ "job_id", "document_id", "span_start", "span_end", "model_id", "prompt_version" ], "title": "ExtractionEvidenceOut", "description": "Where an extracted value was read: the document span and the model that read it." }, "ExtractionJobOut": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "model": { "type": "string", "title": "Model" }, "prompt_version": { "type": "string", "title": "Prompt Version" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "usage": { "additionalProperties": true, "type": "object", "title": "Usage" }, "stats": { "additionalProperties": true, "type": "object", "title": "Stats" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "id", "status", "model", "prompt_version", "usage", "stats" ], "title": "ExtractionJobOut" }, "FieldProblem": { "properties": { "pointer": { "type": "string", "title": "Pointer" }, "message": { "type": "string", "title": "Message" }, "code": { "type": "string", "title": "Code" } }, "type": "object", "required": [ "pointer", "message", "code" ], "title": "FieldProblem", "description": "One invalid request member." }, "FilePreviewOut": { "properties": { "name": { "type": "string", "title": "Name" }, "columns": { "items": { "type": "string" }, "type": "array", "title": "Columns" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Rows", "description": "Records; dates and decimals as text, nested values as JSON." }, "row_count": { "type": "integer", "title": "Row Count", "description": "Rows in the file (those read, for CSV and JSON Lines)." }, "truncated": { "type": "boolean", "title": "Truncated", "description": "Whether the file has more rows than `rows` returned." } }, "type": "object", "required": [ "name", "columns", "rows", "row_count", "truncated" ], "title": "FilePreviewOut", "description": "The first rows of one uploaded file." }, "FingerprintedResolutionIn": { "properties": { "choice": { "type": "string", "title": "Choice" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values" }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "title": "Fingerprint" } }, "type": "object", "required": [ "choice", "fingerprint" ], "title": "FingerprintedResolutionIn" }, "GrantOut": { "properties": { "id": { "type": "string", "title": "Id" }, "domain_id": { "type": "string", "title": "Domain Id" }, "subject": { "type": "string", "title": "Subject" }, "role": { "type": "string", "title": "Role" }, "scope_type": { "$ref": "#/components/schemas/GrantScope" }, "scope_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope Ref" }, "created_by": { "type": "string", "title": "Created By" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "domain_id", "subject", "role", "scope_type", "scope_ref", "created_by", "created_at" ], "title": "GrantOut", "description": "A role of a principal or group in a Domain." }, "GrantScope": { "type": "string", "enum": [ "domain", "kind", "operation", "branch" ], "title": "GrantScope", "description": "What a grant applies to (design 10.2)." }, "HealthSummary": { "properties": { "ok": { "type": "boolean", "title": "Ok", "description": "No violations, orphan Links, required-relation gaps or duplicates of unique Attributes found. Duplicate candidates on title Attributes and stale derived values are reported but do not make a report not ok." }, "kinds": { "type": "integer", "title": "Kinds" }, "records": { "type": "integer", "title": "Records" }, "links": { "type": "integer", "title": "Links" }, "invalid_records": { "type": "integer", "title": "Invalid Records" }, "orphan_links": { "type": "integer", "title": "Orphan Links" }, "required_relation_gaps": { "type": "integer", "title": "Required Relation Gaps" }, "duplicate_groups": { "type": "integer", "title": "Duplicate Groups" }, "stale_kinds": { "type": "integer", "title": "Stale Kinds", "description": "Kinds with derived values missing." }, "sampled_kinds": { "type": "integer", "title": "Sampled Kinds", "description": "Kinds re-validated on a sample only." } }, "type": "object", "required": [ "ok", "kinds", "records", "links", "invalid_records", "orphan_links", "required_relation_gaps", "duplicate_groups", "stale_kinds", "sampled_kinds" ], "title": "HealthSummary" }, "HiddenDuplicates": { "properties": { "attribute": { "type": "string", "title": "Attribute" }, "unique": { "type": "boolean", "title": "Unique", "description": "The Attribute is unique: this is a violation, not a hint." }, "groups": { "type": "integer", "title": "Groups", "description": "Groups of Records sharing a value." }, "records": { "type": "integer", "title": "Records", "description": "Records in those groups." } }, "type": "object", "required": [ "attribute", "unique", "groups", "records" ], "title": "HiddenDuplicates", "description": "Duplicates on an Attribute whose values the caller may not read: counted, not listed\n(which Records share a value would tell that their values are equal)." }, "HistoryOut": { "properties": { "changes": { "type": "integer", "title": "Changes" }, "first_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Revision" }, "last_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Revision" } }, "type": "object", "required": [ "changes" ], "title": "HistoryOut" }, "Include": { "properties": { "select": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Select" }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Limit" }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where" } }, "additionalProperties": false, "type": "object", "title": "Include", "description": "Neighbors to return with each Record, through one Relation." }, "IssueGroup": { "properties": { "code": { "type": "string", "title": "Code", "description": "Validation issue code, e.g. value.required or value.pattern; value.invalid for an Attribute whose values the caller may not read." }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Attribute api name, when one." }, "count": { "type": "integer", "title": "Count" }, "examples": { "items": { "type": "string" }, "type": "array", "title": "Examples", "description": "Keys of some of the Records; none for an Attribute whose values the caller may not read." } }, "type": "object", "required": [ "code", "count", "examples" ], "title": "IssueGroup", "description": "Records failing the same rule of the current schema." }, "ItemDecisionIn": { "properties": { "item": { "type": "string", "minLength": 1, "title": "Item" }, "decision": { "type": "string", "enum": [ "pending", "accepted", "rejected" ], "title": "Decision" }, "edits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Edits", "description": "Reviewer edits; omitted keeps the stored ones, {} clears." } }, "additionalProperties": false, "type": "object", "required": [ "item", "decision" ], "title": "ItemDecisionIn" }, "ItemOut": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "record", "value", "link" ], "title": "Type" }, "seq": { "type": "integer", "title": "Seq" }, "decision": { "type": "string", "enum": [ "pending", "accepted", "rejected" ], "title": "Decision" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "tier": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tier" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "Kind api name (record, value items)." }, "relation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relation", "description": "Relation api name (link items)." }, "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key" }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Attribute api name (value items)." }, "value": { "$ref": "#/components/schemas/JsonValue" }, "current": { "$ref": "#/components/schemas/JsonValue", "description": "The value on the target branch." }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values", "description": "Proposed values by Attribute api name, edits applied." }, "subject": { "additionalProperties": true, "type": "object", "title": "Subject", "description": "What the item proposes, by ids, before edits." }, "evidence": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Evidence" }, "match": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Match" }, "edits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Edits" }, "decided_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decided By" }, "decided_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Decided At" }, "not_applied": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Not Applied", "description": "Why an accepted item is not on the branch." } }, "type": "object", "required": [ "id", "type", "seq", "decision", "confidence", "tier", "model", "subject", "evidence", "match", "edits", "decided_by", "decided_at" ], "title": "ItemOut" }, "ItemSelection": { "properties": { "status": { "items": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "type": "array", "title": "Status" }, "kind": { "items": { "type": "string" }, "type": "array", "title": "Kind", "description": "Kind or Relation api names (or ids)." }, "type": { "items": { "type": "string", "enum": [ "record", "value", "link" ] }, "type": "array", "title": "Type" }, "min_confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Min Confidence" }, "max_confidence": { "anyOf": [ { "type": "number", "maximum": 1.01, "minimum": 0.0 }, { "type": "null" } ], "title": "Max Confidence", "description": "Exclusive upper bound." } }, "additionalProperties": false, "type": "object", "title": "ItemSelection", "description": "Items matching every given filter." }, "JsonValue": {}, "KindCoverage": { "properties": { "kind": { "type": "string", "title": "Kind" }, "records": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Records", "description": "Live Records of the Kind when counted." }, "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Of", "description": "Revision (hex) the statistics were counted at." }, "computed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Computed At" }, "approximate": { "type": "boolean", "title": "Approximate", "description": "The head moved since, or the Kind was counted over a sample." } }, "type": "object", "required": [ "kind", "records", "as_of", "approximate" ], "title": "KindCoverage", "description": "The statistics the coverage of a Kind was read from." }, "KindHealth": { "properties": { "kind": { "type": "string", "title": "Kind" }, "records": { "type": "integer", "title": "Records" }, "last_change": { "anyOf": [ { "$ref": "#/components/schemas/LastChange" }, { "type": "null" } ] }, "violations": { "$ref": "#/components/schemas/ViolationReport" }, "duplicates": { "$ref": "#/components/schemas/DuplicateReport" }, "derived": { "anyOf": [ { "$ref": "#/components/schemas/DerivedReport" }, { "type": "null" } ], "description": "Present for Kinds with derived Attributes." } }, "type": "object", "required": [ "kind", "records", "violations", "duplicates" ], "title": "KindHealth" }, "KindHealthOut": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "summary": { "$ref": "#/components/schemas/HealthSummary" }, "health": { "$ref": "#/components/schemas/KindHealth" }, "relations": { "items": { "$ref": "#/components/schemas/RelationHealth" }, "type": "array", "title": "Relations" } }, "type": "object", "required": [ "revision", "served_from", "domain", "branch", "summary", "health", "relations" ], "title": "KindHealthOut", "description": "Health of one Kind, with the Relations it takes part in." }, "LastChange": { "properties": { "revision": { "type": "string", "title": "Revision" }, "at": { "type": "string", "format": "date-time", "title": "At" } }, "type": "object", "required": [ "revision", "at" ], "title": "LastChange", "description": "The latest Revision on the branch that changed a Record of the Kind." }, "LineageOut": { "properties": { "provenance_id": { "type": "string", "title": "Provenance Id" }, "origin_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Type" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "At" } }, "type": "object", "required": [ "provenance_id" ], "title": "LineageOut" }, "LineageProposalOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "string", "title": "Status" }, "merged_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merged Revision" } }, "type": "object", "required": [ "id", "title", "status" ], "title": "LineageProposalOut" }, "LinkCountOut": { "properties": { "relation": { "type": "string", "title": "Relation", "description": "Relation api name in the direction seen from the Record." }, "direction": { "$ref": "#/components/schemas/LinkDirection" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "relation", "direction", "count" ], "title": "LinkCountOut" }, "LinkDirection": { "type": "string", "enum": [ "forward", "inverse" ], "title": "LinkDirection" }, "LinkLineageOut": { "properties": { "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "origin_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Type", "description": "Provenance origin type." }, "origin": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Origin", "description": "Provenance origin." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Message of the Revision." }, "relation": { "type": "string", "title": "Relation", "description": "Relation api name seen from the Record." }, "direction": { "$ref": "#/components/schemas/LinkDirection" }, "ref": { "type": "string", "title": "Ref", "description": "The Record at the other end." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values" } }, "type": "object", "required": [ "relation", "direction", "ref" ], "title": "LinkLineageOut" }, "LinkOut": { "properties": { "relation": { "type": "string", "title": "Relation" }, "direction": { "$ref": "#/components/schemas/LinkDirection" }, "from_key": { "type": "string", "title": "From Key" }, "to_key": { "type": "string", "title": "To Key" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values" }, "target": { "anyOf": [ { "$ref": "#/components/schemas/RecordRef" }, { "type": "null" } ], "description": "The Record at the other end, as seen from the source." } }, "type": "object", "required": [ "relation", "direction", "from_key", "to_key", "values" ], "title": "LinkOut", "description": "A Link seen from one side: `relation` is the api name in that direction." }, "LinkPage": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "items": { "items": { "$ref": "#/components/schemas/LinkOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "revision", "served_from", "items" ], "title": "LinkPage" }, "LinkRef": { "properties": { "from_key": { "type": "string", "title": "From Key" }, "to_key": { "type": "string", "title": "To Key" } }, "type": "object", "required": [ "from_key", "to_key" ], "title": "LinkRef" }, "Liveness": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "default": "ok" } }, "type": "object", "title": "Liveness", "description": "The process is up." }, "LogPage": { "properties": { "branch": { "type": "string", "title": "Branch" }, "head": { "type": "string", "title": "Head" }, "items": { "items": { "$ref": "#/components/schemas/RevisionOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "branch", "head", "items" ], "title": "LogPage" }, "LogoutResult": { "properties": { "logout_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logout Url", "description": "The provider's end-session URL; null when it offers none or no session was open." } }, "type": "object", "required": [ "logout_url" ], "title": "LogoutResult", "description": "Where to send the browser to sign out at the identity provider too." }, "MatchCondition": { "properties": { "match": { "type": "string", "minLength": 1, "title": "Match" } }, "additionalProperties": false, "type": "object", "required": [ "match" ], "title": "MatchCondition", "description": "Full-text match of the Record (title and searchable Attributes)." }, "Materialization": { "type": "string", "enum": [ "full", "overlay", "none", "building" ], "title": "Materialization", "description": "Branch materialization mode (design 6.11)." }, "MaterializationPhase": { "type": "string", "enum": [ "records", "links", "history", "clear", "tree_history", "tree_rows", "switch", "prune", "derived", "paths", "search", "done" ], "title": "MaterializationPhase", "description": "What the next batch does; `switch` makes the branch a full copy.\n\n`base`: `records`, `links`, `history`, `switch`. `tree`: `clear` (rows left by an\nearlier state), `tree_history`, `tree_rows`, `derived`, `paths`, `switch`. After the\nswitch, a copy that got schema changes reconciles: `prune`, `derived`, `paths`,\n`search`." }, "MaterializationProgress": { "properties": { "phase": { "$ref": "#/components/schemas/MaterializationPhase", "description": "What the next batch copies: `records`, `links`, `history`, then `switch` (the branch becomes a full copy); `done` at the end." }, "rows_done": { "type": "integer", "title": "Rows Done", "description": "Rows of the source branch read so far." }, "rows_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rows Total", "description": "Rows of the source branch to read (Records, Links and history entries at the start of the copy); null until the job has started." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Last failure of the copy job, kept while it is retried and when it failed." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" } }, "type": "object", "required": [ "phase", "rows_done", "rows_total", "error", "updated_at", "finished_at" ], "title": "MaterializationProgress", "description": "How far the background copy of a branch got." }, "MaterializationStatus": { "type": "string", "enum": [ "pending", "running", "done", "failed" ], "title": "MaterializationStatus", "description": "Where a background copy stands." }, "MaterializedOut": { "properties": { "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" }, "changes": { "type": "integer", "title": "Changes" }, "applied": { "type": "integer", "title": "Applied" }, "skipped": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Skipped" } }, "type": "object", "required": [ "revision", "changes", "applied", "skipped" ], "title": "MaterializedOut" }, "MergeIn": { "properties": { "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Message" } }, "type": "object", "title": "MergeIn" }, "MergeOut": { "properties": { "status": { "type": "string", "const": "merged", "title": "Status", "default": "merged" }, "result": { "type": "string", "title": "Result", "description": "`merged`, `fast_forward` or `up_to_date`." }, "revision": { "type": "string", "title": "Revision", "description": "Head of the target branch after the merge." }, "proposal": { "$ref": "#/components/schemas/lorebase_keeper__routes__proposals__ProposalOut" }, "attempt": { "$ref": "#/components/schemas/ConflictsOut" }, "source_deleted": { "type": "boolean", "title": "Source Deleted" }, "replayed": { "type": "boolean", "title": "Replayed" } }, "type": "object", "required": [ "result", "revision", "proposal", "attempt", "source_deleted", "replayed" ], "title": "MergeOut", "description": "A merged Proposal." }, "MergeSuggestionsOut": { "properties": { "merged": { "type": "integer", "title": "Merged", "description": "Suggestions folded into another and removed." }, "kept": { "type": "integer", "title": "Kept", "description": "Suggestions that absorbed others." } }, "type": "object", "required": [ "merged", "kept" ], "title": "MergeSuggestionsOut" }, "NeighborhoodRequest": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, "seeds": { "items": { "$ref": "#/components/schemas/RecordAddress" }, "type": "array", "minItems": 1, "title": "Seeds" }, "depth": { "type": "integer", "minimum": 1.0, "title": "Depth", "default": 1 }, "relations": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Relations", "description": "Relation api names to follow; a forward name follows Links forward, an inverse name backward. Default: every Relation in both directions." }, "max_nodes": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Nodes" }, "max_edges": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Edges" }, "values": { "type": "boolean", "title": "Values", "description": "false: nodes are Record headers (kind, key, title) and edges Link endpoints (relation, from, to), without values; for callers that need the structure only.", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "seeds" ], "title": "NeighborhoodRequest", "description": "Breadth-first expansion from seed Records, bounded by depth and caps (design 8.3)." }, "NeighborhoodResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "nodes": { "items": { "anyOf": [ { "$ref": "#/components/schemas/RecordOut" }, { "$ref": "#/components/schemas/RecordRef" } ] }, "type": "array", "title": "Nodes", "description": "Records reached, nearest first: headers only (`RecordRef`) when the request has `values: false`." }, "edges": { "items": { "anyOf": [ { "$ref": "#/components/schemas/Edge" }, { "$ref": "#/components/schemas/EdgeRef" } ] }, "type": "array", "title": "Edges", "description": "Links between the nodes: endpoints only (`EdgeRef`) when the request has `values: false`." }, "truncated": { "type": "boolean", "title": "Truncated", "default": false } }, "type": "object", "required": [ "revision", "served_from", "nodes", "edges" ], "title": "NeighborhoodResponse" }, "NextHint": { "properties": { "action": { "type": "string", "title": "Action" }, "detail": { "type": "string", "title": "Detail" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Href" }, "permission": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Permission" } }, "type": "object", "required": [ "action", "detail" ], "title": "NextHint", "description": "A next step, in the style of problem details extensions." }, "NotCondition": { "properties": { "not": { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ], "title": "Not" } }, "additionalProperties": false, "type": "object", "required": [ "not" ], "title": "NotCondition" }, "NoteAccepted": { "properties": { "recorded": { "type": "boolean", "title": "Recorded", "description": "False when tracing is disabled or the note was dropped." } }, "type": "object", "required": [ "recorded" ], "title": "NoteAccepted" }, "NoteIn": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Free text; bounded by keeper.trace.max_note_chars." }, "domain_id": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Domain Id", "description": "Domain the note is about; principals holding trace.read there see it. Needs data.read in that Domain." }, "step": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Step", "description": "The agent's own step counter, shown with the note." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "NoteIn" }, "Operator": { "type": "string", "enum": [ "eq", "ne", "lt", "lte", "gt", "gte", "in", "between", "contains", "prefix", "exists", "match", "near" ], "title": "Operator", "description": "Comparison operators; which ones apply depends on the Attribute type." }, "OrderBy": { "properties": { "attr": { "type": "string", "minLength": 1, "title": "Attr" }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "title": "Dir", "default": "asc" } }, "additionalProperties": false, "type": "object", "required": [ "attr" ], "title": "OrderBy", "description": "One ordering term: an Attribute, `key` or `title`. Absent values sort last." }, "OrphanLinks": { "properties": { "count": { "type": "integer", "title": "Count" }, "missing_from": { "type": "integer", "title": "Missing From", "description": "Links whose `from` Record is missing." }, "missing_to": { "type": "integer", "title": "Missing To", "description": "Links whose `to` Record is missing." }, "examples": { "items": { "$ref": "#/components/schemas/LinkRef" }, "type": "array", "title": "Examples" } }, "type": "object", "required": [ "count", "missing_from", "missing_to", "examples" ], "title": "OrphanLinks", "description": "Links, or foreign keys, whose endpoint Record does not exist." }, "PackChangeOut": { "properties": { "revision": { "type": "string", "title": "Revision" }, "at": { "type": "string", "title": "At" }, "ref": { "type": "string", "title": "Ref" }, "change": { "type": "string", "enum": [ "added", "modified", "removed" ], "title": "Change" }, "attributes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Attributes" }, "actor": { "type": "string", "title": "Actor" }, "origin": { "type": "string", "title": "Origin" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "revision", "at", "ref", "change", "actor", "origin", "message" ], "title": "PackChangeOut" }, "PackLineageOut": { "properties": { "ref": { "type": "string", "title": "Ref" }, "attributes": { "items": { "type": "string" }, "type": "array", "title": "Attributes" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" } }, "type": "object", "required": [ "ref", "attributes" ], "title": "PackLineageOut" }, "PackLinkOut": { "properties": { "from": { "type": "string", "title": "From" }, "to": { "type": "string", "title": "To" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values" } }, "type": "object", "required": [ "from", "to" ], "title": "PackLinkOut" }, "PackNeighborOut": { "properties": { "ref": { "type": "string", "title": "Ref" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "depth": { "type": "integer", "title": "Depth" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values", "description": "Absent when trimmed." } }, "type": "object", "required": [ "ref", "depth" ], "title": "PackNeighborOut" }, "PackRecordOut": { "properties": { "ref": { "type": "string", "title": "Ref" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values" }, "updated_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated Revision" } }, "type": "object", "required": [ "ref", "values" ], "title": "PackRecordOut" }, "Page_ApiKeyOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiKeyOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[ApiKeyOut]" }, "Page_AuditEntryOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditEntryOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[AuditEntryOut]" }, "Page_BranchOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BranchOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[BranchOut]" }, "Page_DocumentOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DocumentOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[DocumentOut]" }, "Page_DomainOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DomainOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[DomainOut]" }, "Page_GrantOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/GrantOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[GrantOut]" }, "Page_ItemOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ItemOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[ItemOut]" }, "Page_PrincipalOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PrincipalOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[PrincipalOut]" }, "Page_ProposalOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/lorebase_keeper__routes__proposals__ProposalOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[ProposalOut]" }, "Page_ReconciliationCandidateOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ReconciliationCandidateOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[ReconciliationCandidateOut]" }, "Page_SourceRunOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SourceRunOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[SourceRunOut]" }, "Page_SuggestionOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SuggestionOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[SuggestionOut]" }, "Page_TagOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TagOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "Page[TagOut]" }, "PartitionCount": { "properties": { "partition": { "type": "string", "title": "Partition" }, "element": { "$ref": "#/components/schemas/PartitionType" }, "name": { "type": "string", "title": "Name" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "partition", "element", "name", "count" ], "title": "PartitionCount" }, "PartitionSummary": { "properties": { "partition": { "type": "string", "title": "Partition" }, "element": { "$ref": "#/components/schemas/PartitionType" }, "name": { "type": "string", "title": "Name" }, "added": { "type": "integer", "title": "Added", "default": 0 }, "removed": { "type": "integer", "title": "Removed", "default": 0 }, "modified": { "type": "integer", "title": "Modified", "default": 0 } }, "type": "object", "required": [ "partition", "element", "name" ], "title": "PartitionSummary" }, "PartitionType": { "type": "string", "enum": [ "schema", "kind", "relation" ], "title": "PartitionType" }, "PreviewErrorOut": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Null when the value is masked: only the failure itself is reported." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Null when the value is masked: messages quote values." } }, "type": "object", "required": [ "code", "message" ], "title": "PreviewErrorOut", "description": "Why a value could not be computed for a Record." }, "PreviewItemOut": { "properties": { "key": { "type": "string", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "value": { "$ref": "#/components/schemas/JsonValue", "description": "The canonical value; null when there is none, the masked value (or null with `keeper.reads.sensitivity.omit`) when `masked`." }, "masked": { "type": "boolean", "title": "Masked" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/PreviewErrorOut" }, { "type": "null" } ] } }, "type": "object", "required": [ "key", "title", "value", "masked" ], "title": "PreviewItemOut", "description": "The computed value for one sample Record." }, "PreviewOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "files": { "items": { "$ref": "#/components/schemas/FilePreviewOut" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "domain", "files" ], "title": "PreviewOut", "description": "First rows of uploaded files; nothing is stored." }, "PrincipalOut": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "$ref": "#/components/schemas/PrincipalType" }, "display_name": { "type": "string", "title": "Display Name" }, "external_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Subject" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "type", "display_name", "external_subject", "created_at" ], "title": "PrincipalOut", "description": "A user or service principal." }, "PrincipalType": { "type": "string", "enum": [ "user", "service", "api_key" ], "title": "PrincipalType", "description": "Kind of authenticated actor (design 13.2)." }, "Problem": { "properties": { "type": { "type": "string", "title": "Type" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "integer", "title": "Status" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance" }, "code": { "type": "string", "title": "Code" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" } }, "additionalProperties": true, "type": "object", "required": [ "type", "title", "status", "code" ], "title": "Problem", "description": "Problem details document (schema of every error response)." }, "ProposalCreate": { "properties": { "source_ref": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Source Ref" }, "target_ref": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Target Ref" }, "title": { "type": "string", "maxLength": 300, "minLength": 1, "title": "Title" }, "description": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "source_ref", "target_ref", "title" ], "title": "ProposalCreate", "description": "A new Proposal: merge `source_ref` into `target_ref`." }, "ProposalDetailOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "source_ref": { "type": "string", "title": "Source Ref" }, "target_ref": { "type": "string", "title": "Target Ref" }, "origin": { "$ref": "#/components/schemas/ProposalOrigin" }, "status": { "$ref": "#/components/schemas/ProposalStatus" }, "author": { "type": "string", "title": "Author" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "merged_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merged Revision" }, "policy": { "additionalProperties": true, "type": "object", "title": "Policy", "description": "Merge policy options differing from defaults." }, "checks": { "items": { "$ref": "#/components/schemas/CheckOut" }, "type": "array", "title": "Checks" }, "steward_roles": { "items": { "type": "string" }, "type": "array", "title": "Steward Roles", "description": "Roles that look after the Kinds the changes touch (design 10.7)." }, "assignees": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Assignees", "description": "Principals who can review it as stewards (callers with principal.read only; at most keeper.stewards.max_assignees_listed)." }, "assignees_truncated": { "type": "boolean", "title": "Assignees Truncated", "default": false }, "reviews": { "items": { "$ref": "#/components/schemas/ReviewOut" }, "type": "array", "title": "Reviews" }, "approval": { "$ref": "#/components/schemas/ApprovalOut" }, "attempt": { "anyOf": [ { "$ref": "#/components/schemas/AttemptOut" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "title", "description", "source_ref", "target_ref", "origin", "status", "author", "created_at", "updated_at", "merged_revision", "policy", "checks", "reviews", "approval", "attempt" ], "title": "ProposalDetailOut" }, "ProposalOrigin": { "type": "string", "enum": [ "manual", "source_sync", "extraction", "operation" ], "title": "ProposalOrigin", "description": "What opened a Proposal." }, "ProposalRefOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "string", "title": "Status" }, "source_ref": { "type": "string", "title": "Source Ref" }, "target_ref": { "type": "string", "title": "Target Ref" }, "url": { "type": "string", "title": "Url" }, "created": { "type": "boolean", "title": "Created", "description": "False when an open Proposal of the branch was updated." } }, "type": "object", "required": [ "id", "title", "status", "source_ref", "target_ref", "url", "created" ], "title": "ProposalRefOut", "description": "The Proposal carrying the edits of an agent write." }, "ProposalStatus": { "type": "string", "enum": [ "open", "merged", "closed" ], "title": "ProposalStatus", "description": "Proposal lifecycle." }, "ProposalUpdate": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 300, "minLength": 1 }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "ProposalUpdate", "description": "Title and description; omitted members are left unchanged." }, "ProvenanceOut": { "properties": { "id": { "type": "string", "title": "Id" }, "origin_type": { "type": "string", "title": "Origin Type", "description": "`operation`, `source_sync`, `extraction`, `merge_resolution`, `schema_migration` or `import`." }, "origin": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Origin", "description": "The origin document of that type." }, "actor": { "type": "string", "title": "Actor" }, "at": { "type": "string", "format": "date-time", "title": "At" } }, "type": "object", "required": [ "id", "origin_type", "origin", "actor", "at" ], "title": "ProvenanceOut", "description": "A provenance entry (design 5.11): where a change came from." }, "PurgeIn": { "properties": { "reason": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Reason", "description": "Why, recorded in the audit." }, "confirm": { "type": "string", "minLength": 1, "title": "Confirm", "description": "The document id, to confirm the purge." } }, "additionalProperties": false, "type": "object", "required": [ "reason", "confirm" ], "title": "PurgeIn" }, "Query": { "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "trait": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trait" }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where" }, "select": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Select" }, "include": { "additionalProperties": { "$ref": "#/components/schemas/Include" }, "type": "object", "title": "Include" }, "order_by": { "items": { "$ref": "#/components/schemas/OrderBy" }, "type": "array", "title": "Order By" }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Limit" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "aggregate": { "anyOf": [ { "$ref": "#/components/schemas/Aggregate" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "Query", "description": "A query over the Records of one Kind or of the Kinds implementing a Trait." }, "QueryRequest": { "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "trait": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trait" }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where" }, "select": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Select" }, "include": { "additionalProperties": { "$ref": "#/components/schemas/Include" }, "type": "object", "title": "Include" }, "order_by": { "items": { "$ref": "#/components/schemas/OrderBy" }, "type": "array", "title": "Order By" }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Limit" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "aggregate": { "anyOf": [ { "$ref": "#/components/schemas/Aggregate" }, { "type": "null" } ] }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the Domain's default branch." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, "coverage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Coverage", "description": "Add the coverage block (design 8.11): missing values of the Attributes used, Source freshness. Default: read.coverage.enabled." } }, "additionalProperties": false, "type": "object", "title": "QueryRequest", "description": "A DSL query (design 8.2) and where to read it." }, "QueryResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "items": { "items": { "$ref": "#/components/schemas/RecordOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "aggregate": { "anyOf": [ { "$ref": "#/components/schemas/AggregateOut" }, { "type": "null" } ] }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/CoverageOut" }, { "type": "null" } ], "description": "How complete the answer can be (unless coverage: false)." } }, "type": "object", "required": [ "revision", "served_from", "items" ], "title": "QueryResponse" }, "QuotaReport": { "properties": { "period": { "type": "string", "const": "day", "title": "Period", "default": "day" }, "resets_at": { "type": "string", "format": "date-time", "title": "Resets At", "description": "Start of the next UTC day, when the counters reset." }, "requests": { "$ref": "#/components/schemas/QuotaUse" }, "context_tokens": { "$ref": "#/components/schemas/QuotaUse", "description": "Estimated tokens of context packs delivered." } }, "type": "object", "required": [ "resets_at", "requests", "context_tokens" ], "title": "QuotaReport", "description": "Daily quotas of an API key and what it has used since the last reset." }, "QuotaUse": { "properties": { "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "used": { "type": "integer", "title": "Used" }, "remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Remaining" } }, "type": "object", "required": [ "limit", "used", "remaining" ], "title": "QuotaUse", "description": "Use of one daily quota. Without a limit, `limit` and `remaining` are null." }, "Readiness": { "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ], "title": "Status" }, "checks": { "additionalProperties": { "$ref": "#/components/schemas/CheckReport" }, "type": "object", "title": "Checks" } }, "type": "object", "required": [ "status", "checks" ], "title": "Readiness", "description": "Whether the service can take traffic, with the outcome of each check." }, "RebaseTagsOut": { "properties": { "status": { "type": "string", "enum": [ "committed", "dry_run", "no_op", "queued" ], "title": "Status" }, "branch": { "type": "string", "title": "Branch" }, "head": { "type": "string", "title": "Head", "description": "Branch head the rebase was planned against." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "New Revision; null for dry runs and rows_only." }, "tags": { "items": { "$ref": "#/components/schemas/TagChangeOut" }, "type": "array", "title": "Tags", "description": "Tags the schema change adds." }, "changes": { "items": { "$ref": "#/components/schemas/ElementChangeOut" }, "type": "array", "title": "Changes" }, "change_count": { "type": "integer", "title": "Change Count" }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Issues" }, "issue_count": { "type": "integer", "title": "Issue Count" }, "job": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Job", "description": "The queued store.sensitivity_refresh job (rows_only)." } }, "type": "object", "required": [ "status", "branch", "head", "revision", "tags", "changes", "change_count", "issues", "issue_count" ], "title": "RebaseTagsOut", "description": "Outcome of a tag rebase." }, "RebaseTagsRequest": { "properties": { "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Message" }, "expected_head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Head", "description": "Fail with 409 unless the branch head is this Revision." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Plan without committing or queueing.", "default": false }, "rows_only": { "type": "boolean", "title": "Rows Only", "description": "Leave the branch's schema as it is: queue the batched rewrite of the titles and search vectors it materialized before the default branch's tags.", "default": false } }, "type": "object", "title": "RebaseTagsRequest", "description": "A tag rebase of one branch." }, "ReconciliationBulkIn": { "properties": { "ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Ids" }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationFilterIn" }, { "type": "null" } ] }, "choice": { "type": "string", "enum": [ "policy", "dismiss" ], "title": "Choice" }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationPolicy" }, { "type": "null" } ] }, "reason": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Reason" }, "dry_run": { "type": "boolean", "title": "Dry Run", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "choice", "reason" ], "title": "ReconciliationBulkIn", "description": "One choice over open candidates: the `ids` given, or those matching `filter`." }, "ReconciliationBulkItemOut": { "properties": { "candidate": { "type": "string", "title": "Candidate" }, "status": { "type": "string", "title": "Status", "description": "As a single decision, or `failed`." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "proposal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" } }, "type": "object", "required": [ "candidate", "status" ], "title": "ReconciliationBulkItemOut" }, "ReconciliationBulkOut": { "properties": { "count": { "type": "integer", "title": "Count" }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Counts", "description": "Candidates per status." }, "items": { "items": { "$ref": "#/components/schemas/ReconciliationBulkItemOut" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "count", "counts", "items" ], "title": "ReconciliationBulkOut" }, "ReconciliationCandidateOut": { "properties": { "id": { "type": "string", "title": "Id" }, "branch": { "type": "string", "title": "Branch" }, "type": { "$ref": "#/components/schemas/CandidateType" }, "status": { "$ref": "#/components/schemas/CandidateStatus" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "Kind api name (null when the schema lost it)." }, "kind_id": { "type": "string", "title": "Kind Id" }, "keys": { "items": { "type": "string" }, "type": "array", "title": "Keys" }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Attribute api name; null for duplicates." }, "attribute_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute Id" }, "claims": { "items": { "$ref": "#/components/schemas/ReconciliationClaimOut" }, "type": "array", "title": "Claims" }, "claim_count": { "type": "integer", "title": "Claim Count", "description": "Every distinct claim seen; the newest are listed." }, "signals": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Signals" }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id", "description": "The Proposal that raised the candidate, or that a decision opened." }, "decision": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Decision", "description": "The last decision: choice, claim, policy, reason and the claims then." }, "decided_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decided By" }, "decided_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Decided At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "steward_roles": { "items": { "type": "string" }, "type": "array", "title": "Steward Roles", "description": "Roles that look after its Kind (design 10.7)." }, "assignees": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Assignees", "description": "Principals who can decide it as stewards (callers with principal.read only; at most keeper.stewards.max_assignees_listed)." }, "assignees_truncated": { "type": "boolean", "title": "Assignees Truncated", "default": false } }, "type": "object", "required": [ "id", "branch", "type", "status", "kind", "kind_id", "keys", "attribute", "attribute_id", "claims", "claim_count", "signals", "proposal_id", "decision", "decided_by", "decided_at", "created_at", "updated_at" ], "title": "ReconciliationCandidateOut", "description": "A reconciliation candidate and its claims." }, "ReconciliationChoice": { "type": "string", "enum": [ "claim", "keep_current", "custom", "policy", "merge" ], "title": "ReconciliationChoice" }, "ReconciliationClaimOut": { "properties": { "claim_id": { "type": "string", "title": "Claim Id" }, "value": { "$ref": "#/components/schemas/JsonValue", "description": "Masked when the caller is not cleared for it." }, "value_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value Hash" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Source identity: `source:`, `document:`, `principal:`..." }, "provenance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provenance Id" }, "proposal_item": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Proposal Item" }, "evidence": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Evidence", "description": "Document, chunk, offsets and quote of an extracted value." }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid From" }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Valid To" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At" } }, "additionalProperties": true, "type": "object", "required": [ "claim_id", "value" ], "title": "ReconciliationClaimOut", "description": "One value and where it comes from (design 10.6)." }, "ReconciliationDecisionOut": { "properties": { "status": { "type": "string", "enum": [ "resolved", "proposed", "undecided", "dry_run", "dismissed", "reopened" ], "title": "Status" }, "candidate": { "$ref": "#/components/schemas/ReconciliationCandidateOut" }, "claim_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claim Id", "description": "The claim chosen." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Revision the write committed." }, "proposal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal", "description": "Proposal of a write that needs review (`proposed`)." }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Branch written." }, "edits": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Edits" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "status", "candidate" ], "title": "ReconciliationDecisionOut", "description": "Where a decision left the candidate." }, "ReconciliationFilterIn": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/CandidateType" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, "additionalProperties": false, "type": "object", "title": "ReconciliationFilterIn" }, "ReconciliationPolicy": { "type": "string", "enum": [ "authority", "newest_wins", "prefer_current", "prefer_incoming" ], "title": "ReconciliationPolicy" }, "ReconciliationReasonIn": { "properties": { "reason": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Reason" } }, "additionalProperties": false, "type": "object", "required": [ "reason" ], "title": "ReconciliationReasonIn" }, "ReconciliationResolveIn": { "properties": { "choice": { "$ref": "#/components/schemas/ReconciliationChoice" }, "claim_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Claim Id" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationPolicy" }, { "type": "null" } ] }, "survivor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Survivor", "description": "Key of the Record that stays." }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values", "description": "Values to set on the survivor, by Attribute api name." }, "reason": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Reason" }, "dry_run": { "type": "boolean", "title": "Dry Run", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "choice", "reason" ], "title": "ReconciliationResolveIn", "description": "A decision (design 10.6): `claim` (`claim_id`), `keep_current`, `custom` (`value`),\n`policy` (`policy`) or, for duplicates, `merge` (`survivor`, `values`)." }, "ReconciliationSweepIn": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the default branch." } }, "additionalProperties": false, "type": "object", "title": "ReconciliationSweepIn" }, "ReconciliationSweepOut": { "properties": { "job_id": { "type": "integer", "title": "Job Id" }, "branch": { "type": "string", "title": "Branch" } }, "type": "object", "required": [ "job_id", "branch" ], "title": "ReconciliationSweepOut" }, "RecordAddress": { "properties": { "kind": { "type": "string", "minLength": 1, "title": "Kind" }, "key": { "type": "string", "minLength": 1, "title": "Key" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "key" ], "title": "RecordAddress" }, "RecordChangeOut": { "properties": { "revision": { "type": "string", "title": "Revision" }, "generation": { "type": "integer", "title": "Generation" }, "at": { "type": "string", "format": "date-time", "title": "At" }, "author": { "type": "string", "title": "Author" }, "on_behalf_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Behalf Of" }, "message": { "type": "string", "title": "Message" }, "origin": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Origin", "description": "Origin of the Revision (`type`, `ref`)." }, "change": { "$ref": "#/components/schemas/ChangeKind" }, "attributes": { "items": { "$ref": "#/components/schemas/AttributeChangeOut" }, "type": "array", "title": "Attributes", "description": "Attributes whose value changed, in schema order." }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ProvenanceOut" }, { "type": "null" } ], "description": "Provenance of the change as a whole (a deletion, for one)." } }, "type": "object", "required": [ "revision", "generation", "at", "author", "message", "origin", "change", "attributes" ], "title": "RecordChangeOut", "description": "One Revision that changed the Record on the branch." }, "RecordHistoryOut": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "branch": { "type": "string", "title": "Branch" }, "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "items": { "items": { "$ref": "#/components/schemas/RecordChangeOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "revision", "served_from", "branch", "kind", "key", "items" ], "title": "RecordHistoryOut" }, "RecordLineageOut": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "branch": { "type": "string", "title": "Branch" }, "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "created": { "anyOf": [ { "$ref": "#/components/schemas/RecordChangeOut" }, { "type": "null" } ], "description": "The change that last created the Record." }, "changes": { "type": "integer", "title": "Changes", "description": "Changes of the Record on the branch, at most `read.history.lineage_count_max`." }, "changes_truncated": { "type": "boolean", "title": "Changes Truncated", "description": "The Record has more changes than `changes` (the count stopped at `read.history.lineage_count_max`).", "default": false }, "attributes": { "items": { "$ref": "#/components/schemas/ValueLineageOut" }, "type": "array", "title": "Attributes" }, "sources": { "items": { "type": "string" }, "type": "array", "title": "Sources", "description": "Sources behind the current values, by api name." }, "proposals": { "items": { "$ref": "#/components/schemas/LineageProposalOut" }, "type": "array", "title": "Proposals", "description": "Proposals behind the current values." } }, "type": "object", "required": [ "revision", "served_from", "branch", "kind", "key", "changes", "attributes", "sources", "proposals" ], "title": "RecordLineageOut" }, "RecordOut": { "properties": { "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Values" }, "updated_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated Revision" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "links": { "anyOf": [ { "items": { "$ref": "#/components/schemas/LinkCountOut" }, "type": "array" }, { "type": "null" } ], "title": "Links" }, "lineage": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/LineageOut" }, "type": "object" }, { "type": "null" } ], "title": "Lineage" }, "included": { "anyOf": [ { "additionalProperties": { "items": { "$ref": "#/components/schemas/RecordOut" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Included" } }, "type": "object", "required": [ "kind", "key", "values" ], "title": "RecordOut", "description": "A Record with values keyed by Attribute api name." }, "RecordPage": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "items": { "items": { "$ref": "#/components/schemas/RecordOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "revision", "served_from", "items" ], "title": "RecordPage" }, "RecordRef": { "properties": { "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "type": "object", "required": [ "kind", "key" ], "title": "RecordRef" }, "RecordResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "record": { "$ref": "#/components/schemas/RecordOut" } }, "type": "object", "required": [ "revision", "served_from", "record" ], "title": "RecordResponse" }, "RelationBacking": { "type": "string", "enum": [ "explicit", "foreign_key" ], "title": "RelationBacking", "description": "``explicit``: Links are stored. ``foreign_key``: Links derive from a ``ref`` Attribute." }, "RelationHealth": { "properties": { "relation": { "type": "string", "title": "Relation", "description": "Relation api name, forward direction." }, "from_kind": { "type": "string", "title": "From Kind" }, "to_kind": { "type": "string", "title": "To Kind" }, "backing": { "$ref": "#/components/schemas/RelationBacking" }, "links": { "type": "integer", "title": "Links" }, "orphan_links": { "$ref": "#/components/schemas/OrphanLinks" }, "required": { "type": "boolean", "title": "Required" }, "required_gaps": { "anyOf": [ { "$ref": "#/components/schemas/RequiredGaps" }, { "type": "null" } ], "description": "Present for Relations with `required_from`." }, "direction": { "anyOf": [ { "type": "string", "enum": [ "outgoing", "incoming", "self" ] }, { "type": "null" } ], "title": "Direction", "description": "In a Kind report: the side the Kind is on." } }, "type": "object", "required": [ "relation", "from_kind", "to_kind", "backing", "links", "orphan_links", "required" ], "title": "RelationHealth" }, "RequiredGaps": { "properties": { "missing": { "type": "integer", "title": "Missing" }, "examples": { "items": { "type": "string" }, "type": "array", "title": "Examples", "description": "Keys of some of the Records." } }, "type": "object", "required": [ "missing", "examples" ], "title": "RequiredGaps", "description": "Records of the `from` Kind without the Link a required Relation demands." }, "ResolutionIn": { "properties": { "choice": { "type": "string", "title": "Choice" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values" } }, "type": "object", "required": [ "choice" ], "title": "ResolutionIn", "description": "A decision for one Conflict (`value` or per-member `values` for `custom` only)." }, "ResolutionOut": { "properties": { "fingerprint": { "type": "string", "title": "Fingerprint" }, "choice": { "type": "string", "title": "Choice" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "values": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Values" }, "resolver": { "type": "string", "title": "Resolver" }, "at": { "type": "string", "format": "date-time", "title": "At" }, "matched": { "type": "boolean", "title": "Matched", "default": true } }, "type": "object", "required": [ "fingerprint", "choice", "resolver", "at" ], "title": "ResolutionOut", "description": "A stored resolution; `matched` is false when its Conflict is gone from the attempt." }, "ResolveCandidate": { "properties": { "target": { "type": "string", "enum": [ "kind", "attribute", "value" ], "title": "Target", "description": "What matched: a Kind, an Attribute (by name), or values of an Attribute." }, "kind": { "type": "string", "title": "Kind", "description": "Kind api name." }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Attribute api name (attribute and value candidates)." }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Attribute type, e.g. decimal(12,2)." }, "values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Values", "description": "Stored values the words stand for (value candidates)." }, "predicate": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Predicate", "description": "Ready-to-use where fragment of lorebase_query / POST /query for the Kind (value candidates)." }, "score": { "type": "number", "title": "Score", "description": "Confidence, 0 to 1; higher first." }, "level": { "type": "string", "enum": [ "exact", "synonym", "trigram", "embedding" ], "title": "Level", "description": "How it matched: exact name or value, alias, similar spelling, or values of the Records nearest to the query vector." }, "matched": { "type": "string", "title": "Matched", "description": "The words of the text that matched." }, "records": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Records", "description": "Records holding the values on the branch read (value candidates)." } }, "type": "object", "required": [ "target", "kind", "score", "level", "matched" ], "title": "ResolveCandidate", "description": "A schema element or indexed value some words of the text may stand for." }, "ResolveManyIn": { "properties": { "resolutions": { "items": { "$ref": "#/components/schemas/FingerprintedResolutionIn" }, "type": "array", "minItems": 1, "title": "Resolutions" } }, "type": "object", "required": [ "resolutions" ], "title": "ResolveManyIn" }, "ResolveRequest": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Words to resolve, e.g. a user's question; split into phrases of one to a few words." }, "kinds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Kinds", "description": "Kind api names to look in; default: every Kind you may read." }, "levels": { "anyOf": [ { "items": { "type": "string", "enum": [ "exact", "synonym", "trigram", "embedding" ] }, "type": "array" }, { "type": "null" } ], "title": "Levels", "description": "Matching levels to use (exact, synonym, trigram, embedding); default: those the server enables." }, "query_vector": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Query Vector", "description": "Embedding of `text` (configured model and dimension): enables the embedding level when nothing else matched." }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Limit", "description": "Candidates returned." }, "coverage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Coverage", "description": "Add the coverage block (design 8.11): missing values of the Attributes used, Source freshness. Default: read.coverage.enabled." }, "record_misses": { "type": "boolean", "title": "Record Misses", "description": "false: never keep the phrases that matched nothing for vocabulary suggestions (they are kept only where the operator turned it on).", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "ResolveRequest", "description": "Words to ground in the schema and the indexed values (design 8.9)." }, "ResolveResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "candidates": { "items": { "$ref": "#/components/schemas/ResolveCandidate" }, "type": "array", "title": "Candidates" }, "unmatched": { "items": { "type": "string" }, "type": "array", "title": "Unmatched", "description": "Words no candidate covers (often filler words)." }, "skipped": { "items": { "$ref": "#/components/schemas/ResolveSkipped" }, "type": "array", "title": "Skipped", "description": "Levels that did not run, and why." }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/CoverageOut" }, { "type": "null" } ], "description": "Phrases unknown in this Domain and how many Records miss the Attributes of the candidates (unless coverage: false)." } }, "type": "object", "required": [ "revision", "served_from", "candidates" ], "title": "ResolveResponse" }, "ResolveSkipped": { "properties": { "level": { "type": "string", "title": "Level" }, "reason": { "type": "string", "title": "Reason" } }, "type": "object", "required": [ "level", "reason" ], "title": "ResolveSkipped" }, "RetirementIn": { "properties": { "reason": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Reason", "description": "Why, recorded in the audit." } }, "additionalProperties": false, "type": "object", "required": [ "reason" ], "title": "RetirementIn" }, "ReviewIn": { "properties": { "verdict": { "$ref": "#/components/schemas/ReviewVerdict" }, "comment": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ], "title": "Comment" } }, "type": "object", "required": [ "verdict" ], "title": "ReviewIn" }, "ReviewOut": { "properties": { "id": { "type": "string", "title": "Id" }, "reviewer": { "type": "string", "title": "Reviewer" }, "verdict": { "$ref": "#/components/schemas/ReviewVerdict" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment" }, "at": { "type": "string", "format": "date-time", "title": "At" } }, "type": "object", "required": [ "id", "reviewer", "verdict", "comment", "at" ], "title": "ReviewOut" }, "ReviewResult": { "properties": { "review": { "$ref": "#/components/schemas/ReviewOut" }, "approval": { "$ref": "#/components/schemas/ApprovalOut" } }, "type": "object", "required": [ "review", "approval" ], "title": "ReviewResult" }, "ReviewVerdict": { "type": "string", "enum": [ "approve", "request_changes", "comment" ], "title": "ReviewVerdict", "description": "Outcome of one Proposal review." }, "RevisionEventOut": { "properties": { "sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sequence", "description": "Outbox sequence; the SSE id. Absent in `changes` pages." }, "type": { "type": "string", "title": "Type" }, "domain": { "type": "string", "title": "Domain" }, "branch": { "type": "string", "title": "Branch" }, "revision": { "type": "string", "title": "Revision" }, "parents": { "items": { "type": "string" }, "type": "array", "title": "Parents" }, "generation": { "type": "integer", "title": "Generation" }, "author": { "type": "string", "title": "Author" }, "on_behalf_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Behalf Of" }, "message": { "type": "string", "title": "Message" }, "origin": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Origin" }, "stats": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Stats" }, "created_at": { "type": "string", "title": "Created At" }, "kinds": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Kinds", "description": "Changed Records per Kind api name." }, "relations": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Relations", "description": "Changed Links per Relation api name." }, "schema_changed": { "type": "boolean", "title": "Schema Changed" }, "keys": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object", "title": "Keys", "description": "Changed Record keys per Kind, capped." }, "keys_truncated": { "type": "boolean", "title": "Keys Truncated" } }, "type": "object", "required": [ "type", "domain", "branch", "revision", "parents", "generation", "author", "message", "origin", "stats", "created_at", "kinds", "relations", "schema_changed", "keys", "keys_truncated" ], "title": "RevisionEventOut", "description": "A Revision committed on a branch." }, "RevisionOut": { "properties": { "id": { "type": "string", "title": "Id" }, "parents": { "items": { "type": "string" }, "type": "array", "title": "Parents" }, "root": { "type": "string", "title": "Root" }, "generation": { "type": "integer", "title": "Generation" }, "author": { "type": "string", "title": "Author" }, "on_behalf_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Behalf Of" }, "message": { "type": "string", "title": "Message" }, "origin": { "additionalProperties": true, "type": "object", "title": "Origin" }, "stats": { "additionalProperties": true, "type": "object", "title": "Stats" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "parents", "root", "generation", "author", "message", "origin", "stats", "created_at" ], "title": "RevisionOut" }, "RotationQueued": { "properties": { "job_id": { "type": "integer", "title": "Job Id", "description": "Id of the queued (or already pending) rotation job." } }, "type": "object", "required": [ "job_id" ], "title": "RotationQueued" }, "SchemaAttributeOut": { "properties": { "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Required" }, "derived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Derived" } }, "type": "object", "required": [ "name", "type" ], "title": "SchemaAttributeOut" }, "SchemaChangeOut": { "properties": { "status": { "type": "string", "enum": [ "committed", "dry_run", "no_op" ], "title": "Status" }, "branch": { "type": "string", "title": "Branch" }, "head": { "type": "string", "title": "Head", "description": "Branch head the change set was applied to." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "New Revision; null for dry runs." }, "changes": { "items": { "$ref": "#/components/schemas/ElementChangeOut" }, "type": "array", "title": "Changes" }, "change_count": { "type": "integer", "title": "Change Count" }, "data_changes": { "type": "integer", "title": "Data Changes", "description": "Record and Link changes made by data migrations." }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Issues" }, "issue_count": { "type": "integer", "title": "Issue Count" } }, "type": "object", "required": [ "status", "branch", "head", "revision", "changes", "change_count", "data_changes", "issues", "issue_count" ], "title": "SchemaChangeOut", "description": "Outcome of a schema change set." }, "SchemaChangeRequest": { "properties": { "yaml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yaml", "description": "Full schema document; elements it leaves out are removed." }, "patch": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Patch", "description": "Partial document (same layout as the YAML document): each element replaces the element with the same api name, or is added." }, "remove": { "items": { "$ref": "#/components/schemas/ElementRemoval" }, "type": "array", "title": "Remove" }, "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Message" }, "expected_head": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Head", "description": "Fail with 409 unless the branch head is this Revision." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Validate and plan without committing.", "default": false }, "cascade": { "type": "boolean", "title": "Cascade", "description": "Confirm that removing Kinds or Relations deletes their Records or Links.", "default": false } }, "type": "object", "title": "SchemaChangeRequest", "description": "A schema change set for one branch." }, "SchemaFragmentOut": { "properties": { "kinds": { "items": { "$ref": "#/components/schemas/SchemaKindOut" }, "type": "array", "title": "Kinds" }, "relations": { "items": { "$ref": "#/components/schemas/SchemaRelationOut" }, "type": "array", "title": "Relations" } }, "type": "object", "required": [ "kinds", "relations" ], "title": "SchemaFragmentOut" }, "SchemaKindOut": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "key": { "items": { "type": "string" }, "type": "array", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "attributes": { "items": { "$ref": "#/components/schemas/SchemaAttributeOut" }, "type": "array", "title": "Attributes" } }, "type": "object", "required": [ "name", "key", "attributes" ], "title": "SchemaKindOut" }, "SchemaOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "revision": { "type": "string", "title": "Revision" }, "schema": { "additionalProperties": true, "type": "object", "title": "Schema" }, "search": { "$ref": "#/components/schemas/SchemaSearchOut" } }, "type": "object", "required": [ "domain", "branch", "revision", "schema", "search" ], "title": "SchemaOut", "description": "The schema of a Revision." }, "SchemaRelationOut": { "properties": { "name": { "type": "string", "title": "Name" }, "inverse": { "type": "string", "title": "Inverse" }, "from": { "type": "string", "title": "From" }, "to": { "type": "string", "title": "To" }, "cardinality": { "type": "string", "title": "Cardinality" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SchemaAttributeOut" }, "type": "array" }, { "type": "null" } ], "title": "Attributes" } }, "type": "object", "required": [ "name", "inverse", "from", "to", "cardinality" ], "title": "SchemaRelationOut" }, "SchemaSearchOut": { "properties": { "modes": { "items": { "type": "string", "enum": [ "lexical", "semantic", "hybrid" ] }, "type": "array", "title": "Modes" }, "embedding": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddingOut" }, { "type": "null" } ], "description": "Set when some Kind has `search.embedding_template`: semantic and hybrid search need a `query_vector` made by this model; null otherwise." } }, "type": "object", "required": [ "modes", "embedding" ], "title": "SchemaSearchOut", "description": "How the Domain can be searched at this Revision." }, "SchemaValidateRequest": { "properties": { "yaml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yaml", "description": "Full schema document; elements it leaves out are removed." }, "patch": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Patch", "description": "Partial document (same layout as the YAML document): each element replaces the element with the same api name, or is added." }, "remove": { "items": { "$ref": "#/components/schemas/ElementRemoval" }, "type": "array", "title": "Remove" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id, tag or branch name." } }, "type": "object", "title": "SchemaValidateRequest", "description": "A change set to validate against the schema of a branch or Revision." }, "SchemaValidationOut": { "properties": { "valid": { "type": "boolean", "title": "Valid" }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Issues" }, "issue_count": { "type": "integer", "title": "Issue Count" }, "changes": { "items": { "$ref": "#/components/schemas/ElementChangeOut" }, "type": "array", "title": "Changes" }, "warnings": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Warnings", "description": "Findings that do not block the change, such as a steward role the installation does not define (`schema.steward_role_unknown`)." } }, "type": "object", "required": [ "valid", "issues", "issue_count", "changes" ], "title": "SchemaValidationOut", "description": "Static validation of a change set." }, "SearchCorrection": { "properties": { "word": { "type": "string", "title": "Word" }, "replacements": { "items": { "type": "string" }, "type": "array", "title": "Replacements" } }, "type": "object", "required": [ "word", "replacements" ], "title": "SearchCorrection", "description": "A query word the branch does not hold and the words searched in its place as well.\n\nWords are lexemes of the text search configuration (lowercased, stemmed by its\ndictionaries), as full-text search compares them." }, "SearchHit": { "properties": { "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snippet" }, "score": { "type": "number", "title": "Score" }, "match": { "anyOf": [ { "type": "string", "enum": [ "all", "partial" ] }, { "type": "null" } ], "title": "Match", "description": "How the hit matched q: every term (`all`), or only some of them (`partial`, ranked after every `all` hit); absent for hits found by vector only." } }, "type": "object", "required": [ "kind", "key", "score" ], "title": "SearchHit" }, "SearchRequest": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, "q": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Q", "description": "Text query (web search syntax)." }, "kinds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Kinds", "description": "Kind api names; default: all." }, "traits": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Traits", "description": "Trait api names: each stands for the Kinds implementing it that the caller may read. With `kinds`, the union is searched." }, "lens": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lens", "description": "Lens api name: its Kinds and Traits are searched when the request names neither `kinds` nor `traits`." }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where", "description": "DSL filter; needs exactly one Kind in the searched Kinds." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "lexical", "semantic", "hybrid" ] }, { "type": "null" } ], "title": "Mode", "description": "Default: hybrid with both `q` and `query_vector`, otherwise the one given." }, "query_vector": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Query Vector", "description": "Query embedding of the configured model and dimension." }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Limit" }, "tuning": { "anyOf": [ { "$ref": "#/components/schemas/SearchTuning" }, { "type": "null" } ], "description": "Ranking knobs in place of the `search` settings." } }, "additionalProperties": false, "type": "object", "title": "SearchRequest", "description": "Full-text, vector or hybrid search (design 8.4). Vectors come from the caller." }, "SearchResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "mode": { "type": "string", "title": "Mode" }, "items": { "items": { "$ref": "#/components/schemas/SearchHit" }, "type": "array", "title": "Items" }, "corrections": { "items": { "$ref": "#/components/schemas/SearchCorrection" }, "type": "array", "title": "Corrections", "description": "Typo corrections applied to q; hits found only through them come after the others." }, "truncated_candidates": { "type": "boolean", "title": "Truncated Candidates", "description": "Only a sample of the matches of q (the first ones in index order) was ranked, as happens when every term of q is very common: better matches may exist. Add a rarer term, a Kind or a filter to narrow q.", "default": false }, "semantic_truncated": { "type": "boolean", "title": "Semantic Truncated", "description": "The vector list is shorter than asked for because the index scan reached its bound (search.semantic.max_scan_tuples, or the over-fetched nearest rows) while more Records match the filters: narrow the Kinds or the filter, or raise the bound.", "default": false } }, "type": "object", "required": [ "revision", "served_from", "mode", "items" ], "title": "SearchResponse" }, "SearchTuning": { "properties": { "lexical_weight": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Lexical Weight" }, "semantic_weight": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Semantic Weight" }, "rrf_k": { "anyOf": [ { "type": "integer", "maximum": 10000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Rrf K" }, "trigram_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.1 }, { "type": "null" } ], "title": "Trigram Threshold" }, "trigram_weight": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trigram Weight" }, "typo_candidates": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Typo Candidates" }, "candidates": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Candidates" } }, "additionalProperties": false, "type": "object", "title": "SearchTuning", "description": "Ranking knobs of one search in place of the `search` settings (to compare parameter\nsets). Unset knobs keep their configured value; `candidates` and `typo_candidates` may only\nbe lowered and `trigram_threshold` only raised." }, "Sensitivity": { "type": "string", "enum": [ "pii", "confidential", "restricted" ], "title": "Sensitivity" }, "ServedFrom": { "type": "string", "enum": [ "materialized", "tree" ], "title": "ServedFrom" }, "SessionInfo": { "properties": { "principal_id": { "type": "string", "title": "Principal Id" }, "display_name": { "type": "string", "title": "Display Name" }, "csrf_header": { "type": "string", "title": "Csrf Header", "description": "Header to send the CSRF token in on unsafe requests." }, "csrf_token": { "type": "string", "title": "Csrf Token", "description": "CSRF token of this session." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "End of the session's absolute lifetime." }, "idle_timeout_s": { "type": "integer", "title": "Idle Timeout S", "description": "The session ends after this long without use." } }, "type": "object", "required": [ "principal_id", "display_name", "csrf_header", "csrf_token", "expires_at", "idle_timeout_s" ], "title": "SessionInfo", "description": "The browser session of the caller." }, "SourceFreshness": { "properties": { "kind": { "type": "string", "title": "Kind" }, "source": { "type": "string", "title": "Source", "description": "Source api name." }, "last_synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Synced At", "description": "End of its last successful run (dry runs aside); null: never." }, "stale_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stale After", "description": "The Source's stale_after." }, "stale": { "type": "boolean", "title": "Stale", "description": "Its last successful run is older than stale_after (or it never ran)." }, "unseen_records": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unseen Records", "description": "Records it owns that no run has seen for stale_after (incremental Sources with stale_after), as of the statistics." } }, "type": "object", "required": [ "kind", "source", "last_synced_at", "stale" ], "title": "SourceFreshness", "description": "When a Source feeding a Kind last synchronized, and what it has not seen lately." }, "SourcePreviewOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "revision": { "type": "string", "title": "Revision", "description": "Revision whose schema the change set was applied to." }, "source": { "type": "string", "title": "Source" }, "target_kind": { "type": "string", "title": "Target Kind" }, "attributes": { "items": { "type": "string" }, "type": "array", "title": "Attributes", "description": "Attributes mapped by an expression, by api name." }, "rows": { "items": { "additionalProperties": { "$ref": "#/components/schemas/ExpressionCellOut" }, "type": "object" }, "type": "array", "title": "Rows", "description": "One entry per row sent: the cell of each Attribute in `attributes`." } }, "type": "object", "required": [ "domain", "branch", "revision", "source", "target_kind", "attributes", "rows" ], "title": "SourcePreviewOut", "description": "Values of the expression mappings of a candidate Source on sample rows." }, "SourcePreviewRequest": { "properties": { "yaml": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yaml", "description": "Full schema document; elements it leaves out are removed." }, "patch": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, { "type": "null" } ], "title": "Patch", "description": "Partial document (same layout as the YAML document): each element replaces the element with the same api name, or is added." }, "remove": { "items": { "$ref": "#/components/schemas/ElementRemoval" }, "type": "array", "title": "Remove" }, "source": { "type": "string", "minLength": 1, "title": "Source", "description": "Api name of the Source in the schema the change set produces." }, "rows": { "items": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object" }, "type": "array", "minItems": 1, "title": "Rows", "description": "Sample rows: column name to value (text for CSV, native values for JSON). At most `read.source_preview_max_rows`, each with at most `read.source_preview_max_columns` columns." }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch", "description": "Default: the default branch." }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id, tag or branch name." } }, "type": "object", "required": [ "source", "rows" ], "title": "SourcePreviewRequest", "description": "A candidate schema change set, the Source to preview in it and sample rows." }, "SourceRunOut": { "properties": { "id": { "type": "string", "title": "Id" }, "source": { "type": "string", "title": "Source" }, "status": { "type": "string", "title": "Status" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "stats": { "additionalProperties": true, "type": "object", "title": "Stats" }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision" }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "id", "source", "status", "stats" ], "title": "SourceRunOut" }, "SuggestionDecisionIn": { "properties": { "suggestion": { "type": "string", "minLength": 1, "title": "Suggestion" }, "decision": { "type": "string", "enum": [ "pending", "accepted", "rejected" ], "title": "Decision" }, "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Api name to use instead (accepted only)." } }, "additionalProperties": false, "type": "object", "required": [ "suggestion", "decision" ], "title": "SuggestionDecisionIn" }, "SuggestionOut": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "enum": [ "kind", "attribute", "relation", "kind_alias", "attribute_alias", "value_alias", "attribute_description" ], "title": "Type" }, "name": { "type": "string", "title": "Name", "description": "Proposed api name." }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "Owner Kind of an Attribute, from Kind of a Relation: an api name, or `+Name` for a Kind another suggestion proposes." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target", "description": "To Kind of a Relation." }, "attribute": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attribute", "description": "Vocabulary suggestions: the Attribute they change." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Value aliases: the stored value the alias stands for." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Attribute descriptions: the proposed description." }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels", "description": "Labels as the documents wrote them; the missed phrases of a vocabulary suggestion." }, "support": { "type": "integer", "title": "Support", "description": "Observations, over every document; misses for a vocabulary suggestion." }, "documents": { "type": "integer", "title": "Documents", "description": "Documents it was observed in; 0 for a vocabulary suggestion, which comes from resolution misses rather than documents." }, "confidence": { "type": "number", "title": "Confidence", "description": "Mean confidence of the observations." }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ], "title": "Status" }, "type_guess": { "anyOf": [ { "$ref": "#/components/schemas/TypeGuessOut" }, { "type": "null" } ], "description": "For Attributes: the type the samples suggest." }, "samples": { "items": { "type": "string" }, "type": "array", "title": "Samples" }, "examples": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Examples", "description": "Evidence: document, chunk, offsets into the parsed text, quote; for a vocabulary suggestion the missed phrase, its misses, distinct callers and the similarity that linked it." }, "sources": { "items": { "type": "string" }, "type": "array", "title": "Sources", "description": "Techniques that observed it (rules, models)." }, "duplicate_of": { "anyOf": [ { "$ref": "#/components/schemas/DuplicateOut" }, { "type": "null" } ], "description": "The element of the current schema it duplicates." }, "withheld": { "type": "boolean", "title": "Withheld", "description": "Examples and samples are left out: it matches a sensitive Attribute the caller may not read.", "default": false }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id" }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "decided_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decided By" }, "decided_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Decided At" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "type", "name", "labels", "support", "documents", "confidence", "status", "samples", "examples", "sources", "proposal_id", "branch", "decided_by", "decided_at", "created_at", "updated_at" ], "title": "SuggestionOut" }, "SuggestionProposalOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "branch": { "type": "string", "title": "Branch" }, "changes": { "items": { "$ref": "#/components/schemas/ElementChangeOut" }, "type": "array", "title": "Changes" } }, "type": "object", "required": [ "id", "title", "branch", "changes" ], "title": "SuggestionProposalOut" }, "SyncQueued": { "properties": { "job_id": { "type": "integer", "title": "Job Id", "description": "Id of the queued (or already pending) job." }, "source": { "type": "string", "title": "Source", "description": "Source id." }, "api_name": { "type": "string", "title": "Api Name" }, "dry_run": { "type": "boolean", "title": "Dry Run" } }, "type": "object", "required": [ "job_id", "source", "api_name", "dry_run" ], "title": "SyncQueued" }, "SyncRequest": { "properties": { "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Compute and record the delta without writing to any branch.", "default": false } }, "additionalProperties": false, "type": "object", "title": "SyncRequest" }, "TagChangeOut": { "properties": { "section": { "type": "string", "enum": [ "kinds", "relations" ], "title": "Section" }, "owner": { "type": "string", "title": "Owner", "description": "Api name of the Kind or Relation." }, "attribute": { "type": "string", "title": "Attribute", "description": "Api name of the Attribute." }, "tags": { "items": { "$ref": "#/components/schemas/Sensitivity" }, "type": "array", "title": "Tags" } }, "type": "object", "required": [ "section", "owner", "attribute", "tags" ], "title": "TagChangeOut", "description": "Sensitivity tags added to one Attribute." }, "TagCreate": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Branch whose head is tagged." }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Revision id to tag." } }, "type": "object", "required": [ "name" ], "title": "TagCreate", "description": "A new tag at a Revision or at the head of a branch." }, "TagOut": { "properties": { "name": { "type": "string", "title": "Name" }, "revision": { "type": "string", "title": "Revision" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "type": "object", "required": [ "name", "revision", "created_at", "created_by" ], "title": "TagOut", "description": "An immutable tag." }, "TraceLinkRef": { "properties": { "relation": { "type": "string", "title": "Relation" }, "from": { "$ref": "#/components/schemas/TraceRecordRef" }, "to": { "$ref": "#/components/schemas/TraceRecordRef" } }, "type": "object", "required": [ "relation", "from", "to" ], "title": "TraceLinkRef" }, "TraceRecordRef": { "properties": { "kind": { "type": "string", "title": "Kind" }, "key": { "type": "string", "title": "Key" } }, "type": "object", "required": [ "kind", "key" ], "title": "TraceRecordRef" }, "TraceRefs": { "properties": { "records": { "items": { "$ref": "#/components/schemas/TraceRecordRef" }, "type": "array", "title": "Records" }, "links": { "items": { "$ref": "#/components/schemas/TraceLinkRef" }, "type": "array", "title": "Links" }, "truncated": { "type": "boolean", "title": "Truncated", "description": "More refs were touched than kept or than visible.", "default": false } }, "type": "object", "required": [ "records", "links" ], "title": "TraceRefs" }, "TraceSessionOut": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "actor": { "type": "string", "title": "Actor", "description": "Principal that made the calls." }, "started_at": { "type": "string", "format": "date-time", "title": "Started At" }, "last_at": { "type": "string", "format": "date-time", "title": "Last At" }, "calls": { "type": "integer", "title": "Calls" }, "notes": { "type": "integer", "title": "Notes" }, "domains": { "items": { "type": "string" }, "type": "array", "title": "Domains" }, "tools": { "items": { "type": "string" }, "type": "array", "title": "Tools" }, "proposals": { "items": { "type": "string" }, "type": "array", "title": "Proposals", "description": "Proposals the session opened or acted on." }, "inferred": { "type": "boolean", "title": "Inferred", "description": "Grouped heuristically: the calls carried no session id and were grouped by principal and client while they kept coming (keeper.trace.inferred_session_idle_s).", "default": false } }, "type": "object", "required": [ "session_id", "actor", "started_at", "last_at", "calls", "notes", "domains", "tools", "proposals" ], "title": "TraceSessionOut" }, "TraceSessionPage": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether new requests are traced (keeper.trace.enabled)." }, "items": { "items": { "$ref": "#/components/schemas/TraceSessionOut" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "enabled", "items" ], "title": "TraceSessionPage" }, "TraceStepOut": { "properties": { "step": { "type": "integer", "title": "Step", "description": "Position in the timeline, from 1." }, "seq": { "type": "integer", "title": "Seq" }, "type": { "type": "string", "enum": [ "call", "note" ], "title": "Type" }, "at": { "type": "string", "format": "date-time", "title": "At" }, "actor": { "type": "string", "title": "Actor" }, "principal_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Type" }, "domain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Id" }, "tool": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Route", "description": "Route template, values unexpanded." }, "status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status" }, "latency_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latency Ms" }, "cache": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cache", "description": "Response cache: hit, miss or bypass." }, "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "query": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Query", "description": "The query as sent; filter values kept only on fields that are not sensitive (keeper.trace.capture_filter_values)." }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "Counts, search mode and corrections, budget; no values." }, "refs": { "anyOf": [ { "$ref": "#/components/schemas/TraceRefs" }, { "type": "null" } ] }, "explain": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Explain", "description": "Query plan summaries (`X-Lorebase-Trace: debug`)." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note", "description": "Text of a note; opaque, not markup." }, "proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal Id" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "W3C trace id of the request." }, "inferred": { "type": "boolean", "title": "Inferred", "description": "The step had no session id; its session was inferred.", "default": false }, "withheld": { "type": "boolean", "title": "Withheld", "description": "Another principal's step whose query, corrections and note text the reader may not see (it lacks Domain-wide data.read or a sensitivity clearance).", "default": false } }, "type": "object", "required": [ "step", "seq", "type", "at", "actor" ], "title": "TraceStepOut" }, "TraceTimeline": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "steps": { "items": { "$ref": "#/components/schemas/TraceStepOut" }, "type": "array", "title": "Steps" }, "truncated": { "type": "boolean", "title": "Truncated", "description": "The session has more visible steps than returned." } }, "type": "object", "required": [ "session_id", "steps", "truncated" ], "title": "TraceTimeline" }, "TraverseHopOut": { "properties": { "relation": { "type": "string", "title": "Relation" }, "records": { "items": { "$ref": "#/components/schemas/RecordOut" }, "type": "array", "title": "Records" }, "edges": { "items": { "$ref": "#/components/schemas/Edge" }, "type": "array", "title": "Edges" }, "truncated": { "type": "boolean", "title": "Truncated", "default": false } }, "type": "object", "required": [ "relation", "records", "edges" ], "title": "TraverseHopOut" }, "TraverseRequest": { "properties": { "branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branch" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "At", "description": "Revision id or tag to read at (time travel): key-ordered listings read the tree, other reads a snapshot of the Revision." }, "start": { "$ref": "#/components/schemas/RecordAddress" }, "path": { "items": { "$ref": "#/components/schemas/TraverseStep" }, "type": "array", "minItems": 1, "title": "Path" } }, "additionalProperties": false, "type": "object", "required": [ "start", "path" ], "title": "TraverseRequest", "description": "Follow a path of Relations from one Record (design 8.3)." }, "TraverseResponse": { "properties": { "revision": { "type": "string", "title": "Revision", "description": "Revision the response was served from (hex)." }, "served_from": { "$ref": "#/components/schemas/ServedFrom" }, "start": { "$ref": "#/components/schemas/RecordOut" }, "hops": { "items": { "$ref": "#/components/schemas/TraverseHopOut" }, "type": "array", "title": "Hops" } }, "type": "object", "required": [ "revision", "served_from", "start", "hops" ], "title": "TraverseResponse" }, "TraverseStep": { "properties": { "relation": { "type": "string", "minLength": 1, "title": "Relation", "description": "Forward or inverse Relation api name." }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where", "description": "Filter on the Records reached." }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Limit", "description": "Records reached by this step." } }, "additionalProperties": false, "type": "object", "required": [ "relation" ], "title": "TraverseStep" }, "TrimOut": { "properties": { "step": { "type": "string", "title": "Step" }, "removed": { "type": "integer", "title": "Removed" } }, "type": "object", "required": [ "step", "removed" ], "title": "TrimOut" }, "TypeGuessOut": { "properties": { "type": { "type": "string", "title": "Type", "description": "Attribute type inferred from the samples, e.g. `date`." }, "constraints": { "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "type": "object", "title": "Constraints" }, "confidence": { "type": "number", "title": "Confidence" }, "reasons": { "items": { "type": "string" }, "type": "array", "title": "Reasons" } }, "type": "object", "required": [ "type", "constraints", "confidence", "reasons" ], "title": "TypeGuessOut" }, "UpdateWebhook": { "properties": { "clearances": { "items": { "type": "string", "enum": [ "pii", "confidential", "restricted" ] }, "type": "array", "title": "Clearances", "description": "The new clearances, replacing the current ones. Each one added needs the matching clearance permission on the Domain; removing needs only domain.settings." } }, "additionalProperties": false, "type": "object", "required": [ "clearances" ], "title": "UpdateWebhook" }, "ValidationProblem": { "properties": { "type": { "type": "string", "title": "Type" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "integer", "title": "Status" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance" }, "code": { "type": "string", "title": "Code" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "errors": { "items": { "$ref": "#/components/schemas/FieldProblem" }, "type": "array", "title": "Errors" } }, "additionalProperties": true, "type": "object", "required": [ "type", "title", "status", "code", "errors" ], "title": "ValidationProblem", "description": "Problem details of a rejected request body, query or path." }, "ValueChange": { "properties": { "name": { "type": "string", "title": "Name" }, "old": { "$ref": "#/components/schemas/JsonValue" }, "new": { "$ref": "#/components/schemas/JsonValue" } }, "type": "object", "required": [ "name" ], "title": "ValueChange", "description": "One changed Attribute (Records, Links) or property (schema elements)." }, "ValueLineageOut": { "properties": { "name": { "type": "string", "title": "Name", "description": "Attribute api name." }, "value": { "$ref": "#/components/schemas/JsonValue" }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ProvenanceOut" }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revision", "description": "Revision of the last change." }, "revision_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revision At" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author", "description": "Author of that Revision." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Source api name (`source_sync`)." }, "operation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation", "description": "Operation api name (`operation`)." }, "extraction": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionEvidenceOut" }, { "type": "null" } ] }, "proposal": { "anyOf": [ { "$ref": "#/components/schemas/LineageProposalOut" }, { "type": "null" } ], "description": "The Proposal merged in that Revision, or whose conflict resolution set the value." } }, "type": "object", "required": [ "name" ], "title": "ValueLineageOut", "description": "Where the current value of one Attribute came from." }, "VaultKeysOut": { "properties": { "key_id": { "type": "string", "title": "Key Id", "description": "Encryption key new values are sealed under." }, "token_key_id": { "type": "string", "title": "Token Key Id", "description": "Token key new tokens and fingerprints use." }, "fingerprint_key": { "type": "string", "title": "Fingerprint Key", "description": "Current fingerprint key: token key id/scheme." }, "encryption_keys": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Encryption Keys", "description": "Live rows by encryption key id." }, "fingerprint_keys": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Fingerprint Keys", "description": "Live rows by fingerprint key (`legacy`: written before rotation)." }, "tombstone_keys": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Tombstone Keys", "description": "Fingerprints of erased values by fingerprint key." }, "outdated": { "type": "integer", "title": "Outdated", "description": "Live rows the rotation job still has to make again." }, "removable_keys": { "items": { "type": "string" }, "type": "array", "title": "Removable Keys", "description": "Ids in vault.previous_keys that no row uses: they can be removed." }, "removable_token_keys": { "items": { "type": "string" }, "type": "array", "title": "Removable Token Keys", "description": "Ids in vault.previous_token_keys that no row or tombstone uses." }, "digests": { "type": "string", "title": "Digests", "description": "Key of the keyed digests: vault.digest_key, vault.token_key or installation (the database's own secret)." } }, "type": "object", "required": [ "key_id", "token_key_id", "fingerprint_key", "encryption_keys", "fingerprint_keys", "tombstone_keys", "outdated", "removable_keys", "removable_token_keys", "digests" ], "title": "VaultKeysOut", "description": "Which keys the vault rows use." }, "ViaCondition": { "properties": { "via": { "type": "string", "minLength": 1, "title": "Via" }, "where": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/AllOf" }, { "$ref": "#/components/schemas/AnyOf" }, { "$ref": "#/components/schemas/NotCondition" }, { "$ref": "#/components/schemas/ViaCondition" }, { "$ref": "#/components/schemas/CountCondition" }, { "$ref": "#/components/schemas/MatchCondition" }, { "$ref": "#/components/schemas/DerivedCondition" }, { "$ref": "#/components/schemas/AttributeCondition" } ] }, { "type": "null" } ], "title": "Where" } }, "additionalProperties": false, "type": "object", "required": [ "via" ], "title": "ViaCondition", "description": "A Link of `via` exists, to a Record matching `where` when given." }, "ViolationReport": { "properties": { "checked": { "type": "integer", "title": "Checked", "description": "Records re-validated." }, "sampled": { "type": "boolean", "title": "Sampled", "description": "Only a subset of the Kind's Records was re-validated." }, "invalid_records": { "type": "integer", "title": "Invalid Records", "description": "Re-validated Records with at least one issue." }, "issues": { "items": { "$ref": "#/components/schemas/IssueGroup" }, "type": "array", "title": "Issues" }, "issues_truncated": { "type": "boolean", "title": "Issues Truncated", "default": false } }, "type": "object", "required": [ "checked", "sampled", "invalid_records", "issues" ], "title": "ViolationReport", "description": "Result of re-validating Records with the schema of the branch head." }, "WebhookCreated": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "branches": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Branches" }, "clearances": { "items": { "type": "string" }, "type": "array", "title": "Clearances" }, "created_by": { "type": "string", "title": "Created By" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "secret": { "type": "string", "title": "Secret", "description": "Signing secret. Requests carry `t=,v1=` computed over `.` with the key SHA-256(secret)." } }, "type": "object", "required": [ "id", "url", "events", "created_by", "created_at", "secret" ], "title": "WebhookCreated", "description": "A new webhook; `secret` is shown this once." }, "WebhookList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookOut" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "WebhookList" }, "WebhookOut": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "branches": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Branches" }, "clearances": { "items": { "type": "string" }, "type": "array", "title": "Clearances" }, "created_by": { "type": "string", "title": "Created By" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "url", "events", "created_by", "created_at" ], "title": "WebhookOut" }, "WhoAmI": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "$ref": "#/components/schemas/PrincipalType" }, "display_name": { "type": "string", "title": "Display Name" }, "method": { "type": "string", "title": "Method" }, "subjects": { "items": { "type": "string" }, "type": "array", "title": "Subjects" }, "key_scopes": { "items": { "type": "string" }, "type": "array", "title": "Key Scopes" }, "installation_admin": { "type": "boolean", "title": "Installation Admin" }, "quota": { "anyOf": [ { "$ref": "#/components/schemas/QuotaReport" }, { "type": "null" } ], "description": "Daily quotas of the API key; null for users and without quotas." } }, "type": "object", "required": [ "id", "type", "display_name", "method", "subjects", "key_scopes", "installation_admin" ], "title": "WhoAmI", "description": "The authenticated caller." }, "lorebase_keeper__agents__explain__ProposalOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "string", "title": "Status" }, "merged_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merged Revision" } }, "type": "object", "required": [ "id", "title", "status" ], "title": "ProposalOut" }, "lorebase_keeper__routes__proposals__ProposalOut": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "source_ref": { "type": "string", "title": "Source Ref" }, "target_ref": { "type": "string", "title": "Target Ref" }, "origin": { "$ref": "#/components/schemas/ProposalOrigin" }, "status": { "$ref": "#/components/schemas/ProposalStatus" }, "author": { "type": "string", "title": "Author" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "merged_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merged Revision" }, "policy": { "additionalProperties": true, "type": "object", "title": "Policy", "description": "Merge policy options differing from defaults." }, "checks": { "items": { "$ref": "#/components/schemas/CheckOut" }, "type": "array", "title": "Checks" }, "steward_roles": { "items": { "type": "string" }, "type": "array", "title": "Steward Roles", "description": "Roles that look after the Kinds the changes touch (design 10.7)." }, "assignees": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Assignees", "description": "Principals who can review it as stewards (callers with principal.read only; at most keeper.stewards.max_assignees_listed)." }, "assignees_truncated": { "type": "boolean", "title": "Assignees Truncated", "default": false } }, "type": "object", "required": [ "id", "title", "description", "source_ref", "target_ref", "origin", "status", "author", "created_at", "updated_at", "merged_revision", "policy", "checks" ], "title": "ProposalOut" }, "lorebase_keeper__routes__schema_inference__ProposalOut": { "properties": { "domain": { "type": "string", "title": "Domain" }, "status": { "type": "string", "const": "proposed", "title": "Status", "default": "proposed" }, "schema": { "additionalProperties": true, "type": "object", "title": "Schema" }, "yaml": { "type": "string", "title": "Yaml", "description": "The proposed schema as a YAML document." }, "evidence": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Evidence" }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Issues" }, "issue_count": { "type": "integer", "title": "Issue Count" }, "tables": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Tables" } }, "type": "object", "required": [ "domain", "schema", "yaml", "evidence", "issues", "issue_count", "tables" ], "title": "ProposalOut", "description": "A proposed schema; never committed." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "description": "API key (lbk_...) or OIDC access token.", "scheme": "bearer" } } } }