{ "openapi": "3.1.0", "info": { "title": "Vault meta API", "version": "0.0.0-dev" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": {}, "parameters": {} }, "paths": { "/meta/v1/pipelines": { "get": { "operationId": "pipelines.list", "summary": "List pipelines", "tags": [ "pipelines" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": false, "name": "name", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "name" ], "description": "Sort by id or created_at or updated_at or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "created_by", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } }, "post": { "operationId": "pipelines.create", "summary": "Create a pipeline", "tags": [ "pipelines" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "created_by", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/pipelines/{id}": { "get": { "operationId": "pipelines.get", "summary": "Get a pipeline", "tags": [ "pipelines" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "pipelines.update", "summary": "Update a pipeline", "tags": [ "pipelines" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "pipelines.delete", "summary": "Delete a pipeline", "tags": [ "pipelines" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/meta/v1/pipeline-stages": { "get": { "operationId": "pipeline_stages.list", "summary": "List pipeline_stages", "tags": [ "pipeline_stages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "pipeline_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "open", "won", "lost" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "position", "name" ], "description": "Sort by id or created_at or updated_at or position or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at or position or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "pipeline_id", "name", "kind", "position", "created_by", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } }, "post": { "operationId": "pipeline_stages.create", "summary": "Create a pipeline_stage", "tags": [ "pipeline_stages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pipeline_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pipeline_id", "name", "kind", "position" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "pipeline_id", "name", "kind", "position", "created_by", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/pipeline-stages/{id}": { "get": { "operationId": "pipeline_stages.get", "summary": "Get a pipeline_stage", "tags": [ "pipeline_stages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "pipeline_id", "name", "kind", "position", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "pipeline_stages.update", "summary": "Update a pipeline_stage", "tags": [ "pipeline_stages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "pipeline_id", "name", "kind", "position", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "pipeline_stages.delete", "summary": "Delete a pipeline_stage", "tags": [ "pipeline_stages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "pipelines:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/meta/v1/connections": { "get": { "operationId": "connections.list", "summary": "List connections", "tags": [ "connections" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "last_synced_at" ], "description": "Sort by id or created_at or updated_at or last_synced_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at or last_synced_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "google" ], "description": "The provider of the account; google only for now." }, "account_id": { "type": "string", "description": "The provider's stable id for the account (Google's `sub`). Not the address: an address can change." }, "identity_id": { "type": "string", "format": "uuid", "description": "The own identity that is the connected mailbox's address." }, "owner_id": { "type": "string", "format": "uuid", "description": "The user who owns the connection now; the person whose approval sends from it. A reconnect by another person moves it." }, "status": { "type": "string", "enum": [ "active", "reauth_required", "suspended" ], "description": "active works; reauth_required when the provider refused the stored grant; suspended when the owner is no longer admitted. A reconnect makes it active again." }, "granted_scopes": { "type": "array", "items": { "type": "string" }, "description": "The OAuth scopes the person granted at the provider." }, "connected_at": { "type": "string", "description": "When the connection was made or last reconnected." }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_synced_at": { "type": [ "string", "null" ], "description": "When the mailbox was last brought up to date; null until a sync has finished. Derived, read-only." }, "last_error_code": { "type": [ "string", "null" ], "description": "A short code for the last sync failure; null when the last run was fine or none ran. Derived, read-only." } }, "required": [ "id", "organization_id", "provider", "account_id", "identity_id", "owner_id", "status", "granted_scopes", "connected_at", "created_by", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/meta/v1/connections/{id}": { "get": { "operationId": "connections.get", "summary": "Get a connection", "tags": [ "connections" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "google" ], "description": "The provider of the account; google only for now." }, "account_id": { "type": "string", "description": "The provider's stable id for the account (Google's `sub`). Not the address: an address can change." }, "identity_id": { "type": "string", "format": "uuid", "description": "The own identity that is the connected mailbox's address." }, "owner_id": { "type": "string", "format": "uuid", "description": "The user who owns the connection now; the person whose approval sends from it. A reconnect by another person moves it." }, "status": { "type": "string", "enum": [ "active", "reauth_required", "suspended" ], "description": "active works; reauth_required when the provider refused the stored grant; suspended when the owner is no longer admitted. A reconnect makes it active again." }, "granted_scopes": { "type": "array", "items": { "type": "string" }, "description": "The OAuth scopes the person granted at the provider." }, "connected_at": { "type": "string", "description": "When the connection was made or last reconnected." }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_synced_at": { "type": [ "string", "null" ], "description": "When the mailbox was last brought up to date; null until a sync has finished. Derived, read-only." }, "last_error_code": { "type": [ "string", "null" ], "description": "A short code for the last sync failure; null when the last run was fine or none ran. Derived, read-only." } }, "required": [ "id", "organization_id", "provider", "account_id", "identity_id", "owner_id", "status", "granted_scopes", "connected_at", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "connections.delete", "summary": "Delete a connection", "tags": [ "connections" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "connection management is not proposable" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/meta/v1/connections/authorize": { "post": { "operationId": "connections.authorize", "summary": "Start connecting a Google account: returns the Google consent URL to open in a browser", "description": "Human only: a person connects their own mailbox, because someone has to be at Google's consent screen. The URL is valid for ten minutes. When the person has consented, Google sends the browser back to the vault, which records the connection, its encrypted credential and the mailbox addresses as own identities; nothing is read from the mailbox yet. Answers 501 provider_not_configured when the deployment has no Google OAuth client.", "tags": [ "connections" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "connecting a mailbox needs a person at the provider's consent screen" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "google" ] } }, "required": [ "provider" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorize_url": { "type": "string", "description": "Open this URL in a browser: Google's consent screen. The vault records the connection when Google sends the person back." }, "expires_at": { "type": "string", "description": "When the link stops working (ten minutes)." } }, "required": [ "authorize_url", "expires_at" ] } } } } } } }, "/meta/v1/connections/{id}/sync": { "post": { "operationId": "connections.sync", "summary": "Ask the vault to read a connected mailbox now, instead of waiting for the next scheduled read", "description": "Human only. Records a sync request and starts a background run; answers 202 at once, before anything is read. The run captures new mail, and a mailbox that has never synced starts with a backfill. Read connections.get for last_synced_at (when it finished) and last_error_code (why it did not). 404 for an unknown or disconnected connection; 409 connection_inactive when the connection needs a reconnect (reauth_required or suspended); 501 provider_not_configured when this deployment cannot sync.", "tags": [ "connections" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "connection and credential operations are not proposable" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requested_at": { "type": "string", "description": "When the request was recorded. The mailbox is read by a background run that starts now; read connections.get for last_synced_at and last_error_code." } }, "required": [ "requested_at" ] } } } } } } }, "/meta/v1/memberships": { "get": { "operationId": "memberships.list", "summary": "List memberships", "tags": [ "memberships" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "owner", "member" ] }, "required": false, "name": "role", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at" ], "description": "Sort by id or created_at or updated_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "user_id", "role", "created_by", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/meta/v1/memberships/{id}": { "get": { "operationId": "memberships.get", "summary": "Get a membership", "tags": [ "memberships" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "user_id", "role", "created_by", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/agents": { "get": { "operationId": "agents.list", "summary": "List agents", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "name" ], "description": "Sort by id or created_at or updated_at or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at or name. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "disabled_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "auth_provider": { "type": [ "string", "null" ] }, "auth_subject": { "type": [ "string", "null" ] }, "auth_client_id": { "type": [ "string", "null" ] }, "delegated_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "organization_id", "name", "scopes", "disabled_at", "created_by", "created_at", "updated_at", "auth_provider", "auth_subject", "auth_client_id", "delegated_by" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } }, "post": { "operationId": "agents.create", "summary": "Create a agent", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "access administration is not proposable" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "default": [] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "disabled_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "auth_provider": { "type": [ "string", "null" ] }, "auth_subject": { "type": [ "string", "null" ] }, "auth_client_id": { "type": [ "string", "null" ] }, "delegated_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "organization_id", "name", "scopes", "disabled_at", "created_by", "created_at", "updated_at", "auth_provider", "auth_subject", "auth_client_id", "delegated_by" ] } } } } } } }, "/meta/v1/agents/{id}": { "get": { "operationId": "agents.get", "summary": "Get a agent", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "disabled_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "auth_provider": { "type": [ "string", "null" ] }, "auth_subject": { "type": [ "string", "null" ] }, "auth_client_id": { "type": [ "string", "null" ] }, "delegated_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "organization_id", "name", "scopes", "disabled_at", "created_by", "created_at", "updated_at", "auth_provider", "auth_subject", "auth_client_id", "delegated_by" ] } } } } } }, "patch": { "operationId": "agents.update", "summary": "Update a agent", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "access administration is not proposable" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "add_scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "remove_scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "disabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "disabled_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "auth_provider": { "type": [ "string", "null" ] }, "auth_subject": { "type": [ "string", "null" ] }, "auth_client_id": { "type": [ "string", "null" ] }, "delegated_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "organization_id", "name", "scopes", "disabled_at", "created_by", "created_at", "updated_at", "auth_provider", "auth_subject", "auth_client_id", "delegated_by" ] } } } } } } }, "/meta/v1/api-keys": { "get": { "operationId": "api_keys.list", "summary": "List api_keys", "tags": [ "api_keys" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record." }, "required": false, "description": "Opaque cursor: pass the next_cursor of the previous page back unchanged. With sort it must come from a page with the same sort and order; without sort it is the id of the last record.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "agent_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "last_used_at", "expires_at" ], "description": "Sort by id or created_at or updated_at or last_used_at or expires_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order." }, "required": false, "description": "Sort by id or created_at or updated_at or last_used_at or expires_at. Stored columns need only this list's read scope; derived fields need the scopes that show them. null sorts as the lowest value: first in asc, last in desc. Ties break on id in the same direction. Newest first: sort=created_at&order=desc; for mail use sort=occurred_at&order=desc. Without sort the list is in ascending id order with UUID cursors. Paging is by keyset, not a snapshot: values can rise between pages (or fall), so a record may repeat in asc or be missed in desc. In descending mail date order, newly arrived mail ahead of the cursor is not seen; backfilled older mail behind it is. A complete walk uses the default order. An incremental walk also uses the default ascending id order. Mail created_at uses a temporary sort over the workspace's rows; id is indexed and follows capture order.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc (default) or desc. Needs sort." }, "required": false, "description": "Sort direction: asc (default) or desc. Needs sort.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "agent_id", "prefix", "last_used_at", "revoked_at", "expires_at", "created_by", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null at the end. Pass it back as after, with the same sort and order." } }, "required": [ "data", "next_cursor" ] } } } } } }, "post": { "operationId": "api_keys.create", "summary": "Issue an API key for an agent; the key is shown once", "tags": [ "api_keys" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "access administration and credentials are not proposable" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "agent_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id", "organization_id", "agent_id", "prefix", "last_used_at", "revoked_at", "expires_at", "created_by", "created_at", "updated_at", "key" ] } } } } } } }, "/meta/v1/api-keys/{id}": { "get": { "operationId": "api_keys.get", "summary": "Get a api_key", "tags": [ "api_keys" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "agent_id", "prefix", "last_used_at", "revoked_at", "expires_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/users": { "get": { "operationId": "users.list", "summary": "List the organisation's members as users", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "email", "name", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_cursor" ] } } } } } } }, "/meta/v1/users/{id}": { "get": { "operationId": "users.get", "summary": "Get a user", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "email", "name", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/api-keys/{id}/revoke": { "post": { "operationId": "api_keys.revoke", "summary": "Revoke an API key", "tags": [ "api_keys" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "access administration and credentials are not proposable" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "agent_id", "prefix", "last_used_at", "revoked_at", "expires_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/meta/v1/me": { "get": { "operationId": "me.get", "summary": "Who am I: the principal (user or agent), memberships and the active organisation", "tags": [ "account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "user", "agent" ] } }, "required": [ "id", "kind" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" } }, "required": [ "id", "email", "name", "email_verified" ] }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "delegated_by": { "type": [ "string", "null" ], "format": "uuid" }, "auth_client_id": { "type": [ "string", "null" ] }, "auth_subject": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "delegated_by", "auth_client_id", "auth_subject" ] }, "client_id": { "type": [ "string", "null" ] }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "organization_id", "organization_name", "role" ] } }, "active_organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "member", null ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "role", "scopes" ] } }, "required": [ "principal", "user", "agent", "client_id", "memberships", "active_organization" ] } } } } } } }, "/meta/v1/schema": { "get": { "operationId": "schema.get", "summary": "Describe the workspace database's built-in tables, columns, keys and the API resource behind each", "tags": [ "schema" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "engine": { "type": "string", "enum": [ "d1" ] }, "kinds": { "type": "object", "additionalProperties": { "type": "string" }, "description": "How each logical kind is stored." }, "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "origin": { "type": "string", "enum": [ "built_in" ] }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "associable": { "type": "boolean" }, "resource": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "surface": { "type": "string", "enum": [ "api", "meta" ] }, "path": { "type": "string", "description": "The full path of the collection, for example /api/v1/tasks." }, "operations": { "type": "array", "items": { "type": "string" } }, "read_scope": { "type": "string" }, "write_scope": { "type": [ "string", "null" ] }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "A value the list's `sort` parameter accepts: a column of the record or a derived field." }, "kind": { "type": "string", "description": "The logical kind of the sort value (see `kinds`): timestamp, uuid, text or integer." }, "indexed": { "type": "boolean", "description": "True when an index serves this sort. False is a stated cost: the database sorts the organisation's live rows in a temporary b-tree." } }, "required": [ "name", "kind", "indexed" ] }, "description": "The sorts the list accepts, in the order it accepts them (convention first, then the natural fields); empty when the list takes no `sort`." } }, "required": [ "name", "surface", "path", "operations", "read_scope", "write_scope", "sorts" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "The declared SQL type, as the database reports it (TEXT, INTEGER)." }, "kind": { "type": [ "string", "null" ], "description": "The logical kind (see `kinds`), or null if the code does not know the column." }, "nullable": { "type": "boolean" }, "primary_key": { "type": "boolean" }, "default": { "type": [ "string", "null" ], "description": "The declared default expression, or null." }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "values": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The allowed values when the record schema declares an enum for the field." }, "exposed": { "type": "boolean", "description": "True when the column is a field of the API record of the table's resource." }, "references": { "type": [ "object", "null" ], "properties": { "table": { "type": "string" }, "column": { "type": "string" } }, "required": [ "table", "column" ], "description": "The table and primary-key column this column points at." } }, "required": [ "name", "type", "kind", "nullable", "primary_key", "default", "label", "description", "values", "exposed", "references" ] } }, "derived": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "description": "The logical kind of the value (see `kinds`)." }, "nullable": { "type": "boolean" }, "writable": { "type": "boolean", "enum": [ false ], "description": "Derived fields are computed when the record is read and can never be written." }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "requires": { "type": [ "string", "null" ], "description": "The scope needed to see the field (it is absent from the record without it), or null." }, "filters": { "type": "array", "items": { "type": "string" }, "description": "The list filters on this field." }, "sortable": { "type": "boolean", "description": "Whether the list can be sorted by this field." } }, "required": [ "name", "kind", "nullable", "writable", "label", "description", "requires", "filters", "sortable" ] }, "description": "Record fields computed from other tables when read; not columns." }, "foreign_keys": { "type": "array", "items": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "references": { "type": "object", "properties": { "table": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "table", "columns" ] }, "on_delete": { "type": "string" } }, "required": [ "columns", "references", "on_delete" ] } } }, "required": [ "name", "origin", "label", "description", "associable", "resource", "columns", "derived", "foreign_keys" ] } }, "associations": { "type": "object", "properties": { "table": { "type": "string" }, "relations": { "type": "array", "items": { "type": "string" } }, "associable": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } }, "required": [ "table", "relations", "associable", "description" ] } }, "required": [ "engine", "kinds", "tables", "associations" ] } } } } } } } }, "webhooks": {} }