{ "openapi": "3.1.0", "info": { "title": "Vault records API", "version": "0.0.0-dev" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": {}, "parameters": {} }, "paths": { "/api/v1/tasks": { "get": { "operationId": "tasks.list", "summary": "List tasks", "tags": [ "tasks" ], "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": [ "open", "done" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "assignee_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tag_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "due_at", "title" ], "description": "Sort by id or created_at or updated_at or due_at or title. 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 due_at or title. 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" }, "title": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "notes", "status", "due_at", "completed_at", "assignee_id", "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": "tasks.create", "summary": "Create a task", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tasks:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": [ "string", "null" ], "maxLength": 10000 }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "notes", "status", "due_at", "completed_at", "assignee_id", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/tasks/{id}": { "get": { "operationId": "tasks.get", "summary": "Get a task", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "title", "notes", "status", "due_at", "completed_at", "assignee_id", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "tasks.update", "summary": "Update a task", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tasks:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": [ "string", "null" ], "maxLength": 10000 }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "done" ] }, "due_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "notes", "status", "due_at", "completed_at", "assignee_id", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "tasks.delete", "summary": "Delete a task", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tasks:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/companies": { "get": { "operationId": "companies.list", "summary": "List companies", "tags": [ "companies" ], "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", "maxLength": 253 }, "required": false, "name": "domain", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tag_id", "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" }, "domain": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "domain", "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": "companies.create", "summary": "Create a company", "tags": [ "companies" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "companies:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "domain": { "type": [ "string", "null" ], "maxLength": 253 } }, "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" }, "domain": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "domain", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/companies/{id}": { "get": { "operationId": "companies.get", "summary": "Get a company", "tags": [ "companies" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "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" }, "domain": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "name", "domain", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "companies.update", "summary": "Update a company", "tags": [ "companies" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "companies: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": 500 }, "domain": { "type": [ "string", "null" ], "maxLength": 253 } }, "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" }, "domain": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "domain", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "companies.delete", "summary": "Delete a company", "tags": [ "companies" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "companies:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/contacts": { "get": { "operationId": "contacts.list", "summary": "List contacts", "tags": [ "contacts" ], "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": "company_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "tag_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only contacts last contacted at or after this ISO-8601 time (Z or an offset). Needs interactions:read." }, "required": false, "description": "Only contacts last contacted at or after this ISO-8601 time (Z or an offset). Needs interactions:read.", "name": "contacted_since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only contacts last contacted before this ISO-8601 time (Z or an offset), including those never last. Needs interactions:read." }, "required": false, "description": "Only contacts last contacted before this ISO-8601 time (Z or an offset), including those never last. Needs interactions:read.", "name": "not_contacted_since", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true: only contacts never contacted; false: only contacts contacted at least once. Needs interactions:read." }, "required": false, "description": "true: only contacts never contacted; false: only contacts contacted at least once. Needs interactions:read.", "name": "never_contacted", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only contacts last interacted with at or after this ISO-8601 time (Z or an offset). Needs interactions:read." }, "required": false, "description": "Only contacts last interacted with at or after this ISO-8601 time (Z or an offset). Needs interactions:read.", "name": "interacted_since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only contacts last interacted with before this ISO-8601 time (Z or an offset), including those never last interacted with. Needs interactions:read." }, "required": false, "description": "Only contacts last interacted with before this ISO-8601 time (Z or an offset), including those never last interacted with. Needs interactions:read.", "name": "not_interacted_since", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true: only contacts never interacted with; false: only contacts interacted with at least once. Needs interactions:read." }, "required": false, "description": "true: only contacts never interacted with; false: only contacts interacted with at least once. Needs interactions:read.", "name": "never_interacted", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "name", "last_contacted_at", "last_interacted_at" ], "description": "Sort by id or created_at or updated_at or name or last_contacted_at or last_interacted_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 name or last_contacted_at or last_interacted_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" }, "name": { "type": [ "string", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "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": "contacts.create", "summary": "Create a contact", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "company_id": { "type": [ "string", "null" ], "format": "uuid" } }, "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", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/contacts/{id}": { "get": { "operationId": "contacts.get", "summary": "Get a contact", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "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", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "contacts.update", "summary": "Update a contact", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts: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", "null" ], "minLength": 1, "maxLength": 500 }, "company_id": { "type": [ "string", "null" ], "format": "uuid" } }, "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", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "contacts.delete", "summary": "Delete a contact", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/identities": { "get": { "operationId": "identities.list", "summary": "List identities", "tags": [ "identities" ], "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": [ "email", "phone" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 320 }, "required": false, "name": "value", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "contact_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "own", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "value" ], "description": "Sort by id or created_at or updated_at or value. 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 value. 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" }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "own": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "contact_id", "own", "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": "identities.create", "summary": "Create a identity", "tags": [ "identities" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "contact_id": { "type": "string", "format": "uuid" }, "own": { "type": "boolean", "enum": [ true ] } }, "required": [ "kind", "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "own": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "contact_id", "own", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/identities/{id}": { "get": { "operationId": "identities.get", "summary": "Get a identity", "tags": [ "identities" ], "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" }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "own": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "contact_id", "own", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "identities.update", "summary": "Update a identity", "tags": [ "identities" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "own": { "type": "boolean", "enum": [ true ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "own": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "contact_id", "own", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "identities.delete", "summary": "Delete a identity", "tags": [ "identities" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/notes": { "get": { "operationId": "notes.list", "summary": "List notes", "tags": [ "notes" ], "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": "created_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "title" ], "description": "Sort by id or created_at or updated_at or title. 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 title. 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" }, "title": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "content", "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": "notes.create", "summary": "Create a note", "tags": [ "notes" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "notes:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "content" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "content", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/notes/{id}": { "get": { "operationId": "notes.get", "summary": "Get a note", "tags": [ "notes" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "title", "content", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "notes.update", "summary": "Update a note", "tags": [ "notes" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "notes:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "title", "content", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "notes.delete", "summary": "Delete a note", "tags": [ "notes" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "notes:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/tags": { "get": { "operationId": "tags.list", "summary": "List tags", "tags": [ "tags" ], "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", "format": "uuid" }, "required": false, "name": "created_by", "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" }, "description": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "description", "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": "tags.create", "summary": "Create a tag", "tags": [ "tags" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tags:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 } }, "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" }, "description": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "description", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/tags/{id}": { "get": { "operationId": "tags.get", "summary": "Get a tag", "tags": [ "tags" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "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" }, "description": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "name", "description", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "tags.update", "summary": "Update a tag", "tags": [ "tags" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tags: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 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 } }, "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" }, "description": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "description", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "tags.delete", "summary": "Delete a tag", "tags": [ "tags" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "tags:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/deals": { "get": { "operationId": "deals.list", "summary": "List deals", "tags": [ "deals" ], "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", "format": "uuid" }, "required": false, "name": "stage_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "owner_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "created_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "Only deals whose stage is of this kind: open, won or lost." }, "required": false, "description": "Only deals whose stage is of this kind: open, won or lost.", "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only deals linked to this tag." }, "required": false, "description": "Only deals linked to this tag.", "name": "tag_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only deals linked to this company (an association)." }, "required": false, "description": "Only deals linked to this company (an association).", "name": "company_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Only deals linked to this contact (an association)." }, "required": false, "description": "Only deals linked to this contact (an association).", "name": "contact_id", "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" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "The kind of the deal's stage: open, won or lost. Derived, read-only." }, "amount_minor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "closed_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "pipeline_id", "stage_id", "amount_minor", "currency", "expected_close_date", "owner_id", "closed_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": "deals.create", "summary": "Create a deal", "tags": [ "deals" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "deals:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "amount_minor": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Optional, in the currency's minor units (cents; for JPY the unit). Needs a currency." }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{3}$", "description": "Optional ISO 4217 code such as USD; stored upper case." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date", "description": "Optional calendar date, YYYY-MM-DD." }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" } }, "required": [ "name", "stage_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" }, "name": { "type": "string" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "The kind of the deal's stage: open, won or lost. Derived, read-only." }, "amount_minor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "closed_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "pipeline_id", "stage_id", "amount_minor", "currency", "expected_close_date", "owner_id", "closed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/deals/{id}": { "get": { "operationId": "deals.get", "summary": "Get a deal", "tags": [ "deals" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "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" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "The kind of the deal's stage: open, won or lost. Derived, read-only." }, "amount_minor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "closed_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "organization_id", "name", "pipeline_id", "stage_id", "amount_minor", "currency", "expected_close_date", "owner_id", "closed_at", "created_by", "created_at", "updated_at" ] } } } } } }, "patch": { "operationId": "deals.update", "summary": "Update a deal", "tags": [ "deals" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "deals: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": 200 }, "amount_minor": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Optional, in the currency's minor units (cents; for JPY the unit). Needs a currency." }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{3}$", "description": "Optional ISO 4217 code such as USD; stored upper case." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date", "description": "Optional calendar date, YYYY-MM-DD." }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" } }, "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" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "The kind of the deal's stage: open, won or lost. Derived, read-only." }, "amount_minor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "closed_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "pipeline_id", "stage_id", "amount_minor", "currency", "expected_close_date", "owner_id", "closed_at", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "deals.delete", "summary": "Delete a deal", "tags": [ "deals" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "deals:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/deals/{id}/move-stage": { "post": { "operationId": "deals.move_stage", "summary": "Move a deal (also called an opportunity) to another stage of its pipeline", "description": "The only way to change a deal's stage. The stage must be a stage of the deal's own pipeline (see pipeline_stages_list). Moving into a won or lost stage closes the deal (closed_at); moving to an open stage reopens it. Moving to the stage the deal is already in changes nothing. Emits deal.stage_changed.", "tags": [ "deals" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "deals:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "type": "string", "format": "uuid" } }, "required": [ "stage_id" ], "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" }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "The kind of the deal's stage: open, won or lost. Derived, read-only." }, "amount_minor": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "closed_at": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "pipeline_id", "stage_id", "amount_minor", "currency", "expected_close_date", "owner_id", "closed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/threads": { "get": { "operationId": "threads.list", "summary": "List threads", "tags": [ "threads" ], "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": [ "email" ] }, "required": false, "name": "channel", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "subject" ], "description": "Sort by id or created_at or subject. 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 subject. 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" }, "channel": { "type": "string", "enum": [ "email" ] }, "subject": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "channel", "subject", "created_by", "created_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" ] } } } } } } }, "/api/v1/threads/{id}": { "get": { "operationId": "threads.get", "summary": "Get a thread", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "email" ] }, "subject": { "type": [ "string", "null" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "channel", "subject", "created_by", "created_at" ] } } } } } } }, "/api/v1/messages": { "get": { "operationId": "messages.list", "summary": "List messages", "tags": [ "messages" ], "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": "thread_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "email" ] }, "required": false, "name": "channel", "in": "query" }, { "schema": { "type": "string", "enum": [ "message", "reaction" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 998 }, "required": false, "name": "external_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 998 }, "required": false, "name": "in_reply_to", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "occurred_at" ], "description": "Sort by id or created_at or occurred_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 occurred_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" }, "thread_id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "email" ] }, "kind": { "type": "string", "enum": [ "message", "reaction" ] }, "external_id": { "type": "string" }, "in_reply_to": { "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_name": { "type": "string" }, "full_name": { "type": "string" }, "is_bot": { "type": "boolean" } }, "required": [ "user_id", "user_name", "full_name", "is_bot" ] }, "occurred_at": { "type": "string" }, "preview": { "type": "string" }, "version": { "type": "integer" }, "retracted_at": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "type": { "type": "string", "enum": [ "image", "file", "video", "audio" ] }, "name": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "inline": { "type": "boolean" }, "content_id": { "type": [ "string", "null" ] }, "fetch_status": { "type": "string", "enum": [ "stored", "pending", "failed", "skipped" ] }, "file_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "position", "type", "name", "mime_type", "size_bytes", "inline", "content_id", "fetch_status", "file_id" ] } }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "thread_id", "channel", "kind", "external_id", "in_reply_to", "author", "occurred_at", "preview", "version", "retracted_at", "attachments", "created_by", "created_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" ] } } } } } } }, "/api/v1/messages/{id}": { "get": { "operationId": "messages.get", "summary": "Get a message", "tags": [ "messages" ], "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" }, "thread_id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "email" ] }, "kind": { "type": "string", "enum": [ "message", "reaction" ] }, "external_id": { "type": "string" }, "in_reply_to": { "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_name": { "type": "string" }, "full_name": { "type": "string" }, "is_bot": { "type": "boolean" } }, "required": [ "user_id", "user_name", "full_name", "is_bot" ] }, "occurred_at": { "type": "string" }, "preview": { "type": "string" }, "version": { "type": "integer" }, "retracted_at": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "type": { "type": "string", "enum": [ "image", "file", "video", "audio" ] }, "name": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "inline": { "type": "boolean" }, "content_id": { "type": [ "string", "null" ] }, "fetch_status": { "type": "string", "enum": [ "stored", "pending", "failed", "skipped" ] }, "file_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "position", "type", "name", "mime_type", "size_bytes", "inline", "content_id", "fetch_status", "file_id" ] } }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "thread_id", "channel", "kind", "external_id", "in_reply_to", "author", "occurred_at", "preview", "version", "retracted_at", "attachments", "created_by", "created_at" ] } } } } } } }, "/api/v1/interactions": { "get": { "operationId": "interactions.list", "summary": "List interactions", "tags": [ "interactions" ], "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": [ "message", "reaction" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "enum": [ "email" ] }, "required": false, "name": "channel", "in": "query" }, { "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "thread_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "message_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "identity_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "contact_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "occurred_at" ], "description": "Sort by id or created_at or occurred_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 occurred_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" }, "kind": { "type": "string", "enum": [ "message", "reaction" ] }, "channel": { "type": "string", "enum": [ "email" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "occurred_at": { "type": "string" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "message_id": { "type": [ "string", "null" ], "format": "uuid" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "identity_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "from", "to", "cc", "bcc" ] } }, "required": [ "identity_id", "role" ] } }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "channel", "direction", "occurred_at", "thread_id", "message_id", "participants", "created_by", "created_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" ] } } } } } } }, "/api/v1/interactions/{id}": { "get": { "operationId": "interactions.get", "summary": "Get a interaction", "tags": [ "interactions" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "associations" ] }, "required": false, "name": "include", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "message", "reaction" ] }, "channel": { "type": "string", "enum": [ "email" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "occurred_at": { "type": "string" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "message_id": { "type": [ "string", "null" ], "format": "uuid" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "identity_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "from", "to", "cc", "bcc" ] } }, "required": [ "identity_id", "role" ] } }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "associations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "associations_truncated": { "type": "boolean" } }, "required": [ "id", "kind", "channel", "direction", "occurred_at", "thread_id", "message_id", "participants", "created_by", "created_at" ] } } } } } } }, "/api/v1/files": { "get": { "operationId": "files.list", "summary": "List files", "tags": [ "files" ], "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", "pattern": "^[0-9a-fA-F]{64}$" }, "required": false, "name": "sha256", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "name" ], "description": "Sort by id or created_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 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" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "mime_type", "size_bytes", "sha256", "created_by", "created_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" ] } } } } } } }, "/api/v1/files/{id}": { "get": { "operationId": "files.get", "summary": "Get a file", "tags": [ "files" ], "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" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "mime_type", "size_bytes", "sha256", "created_by", "created_at" ] } } } } } } }, "/api/v1/contact-files": { "get": { "operationId": "contact_files.list", "summary": "List contact_files", "tags": [ "contact_files" ], "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": "contact_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "file_id", "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" }, "contact_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "contact_id", "file_id", "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": "contact_files.create", "summary": "Create a contact_file", "tags": [ "contact_files" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "file links are not proposable yet" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" } }, "required": [ "contact_id", "file_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "contact_id", "file_id", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/contact-files/{id}": { "get": { "operationId": "contact_files.get", "summary": "Get a contact_file", "tags": [ "contact_files" ], "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" }, "contact_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "contact_id", "file_id", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "contact_files.delete", "summary": "Delete a contact_file", "tags": [ "contact_files" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "file links are not proposable yet" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/company-files": { "get": { "operationId": "company_files.list", "summary": "List company_files", "tags": [ "company_files" ], "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": "company_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "file_id", "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" }, "company_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "company_id", "file_id", "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": "company_files.create", "summary": "Create a company_file", "tags": [ "company_files" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "file links are not proposable yet" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" } }, "required": [ "company_id", "file_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "company_id", "file_id", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/company-files/{id}": { "get": { "operationId": "company_files.get", "summary": "Get a company_file", "tags": [ "company_files" ], "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" }, "company_id": { "type": "string", "format": "uuid" }, "file_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "company_id", "file_id", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "company_files.delete", "summary": "Delete a company_file", "tags": [ "company_files" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "file links are not proposable yet" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/associations": { "get": { "operationId": "associations.list", "summary": "List the associations of a record", "description": "The records linked to the anchor (`type`, `id`), oriented from the anchor, pages ascending by association id. Neighbours of a type the caller cannot read are omitted.", "tags": [ "associations" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "read-only operation" }, "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "required": true, "name": "type", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "neighbour_type", "in": "query" }, { "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" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "neighbour_type": { "type": "string" }, "neighbour_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" } }, "required": [ "id", "relation", "neighbour_type", "neighbour_id", "created_by", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_cursor" ] } } } } } }, "post": { "operationId": "associations.create", "summary": "Link two records", "description": "Links two live records of associable tables. The pair may be given in either order; the response shows the canonical order.", "tags": [ "associations" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "associations:request_approval", "also_requires": "read on the endpoint type of each end (a_type, b_type)" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "a_type": { "type": "string", "maxLength": 64 }, "a_id": { "type": "string", "format": "uuid" }, "b_type": { "type": "string", "maxLength": 64 }, "b_id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] } }, "required": [ "a_type", "a_id", "b_type", "b_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "a_type": { "type": "string" }, "a_id": { "type": "string", "format": "uuid" }, "b_type": { "type": "string" }, "b_id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "a_type", "a_id", "b_type", "b_id", "relation", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/associations/{id}": { "get": { "operationId": "associations.get", "summary": "Get an association", "tags": [ "associations" ], "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" }, "a_type": { "type": "string" }, "a_id": { "type": "string", "format": "uuid" }, "b_type": { "type": "string" }, "b_id": { "type": "string", "format": "uuid" }, "relation": { "type": "string", "enum": [ "related_to" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "a_type", "a_id", "b_type", "b_id", "relation", "created_by", "created_at", "updated_at" ] } } } } } }, "delete": { "operationId": "associations.delete", "summary": "Unlink two records", "tags": [ "associations" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "associations:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content" } } } }, "/api/v1/messages/{id}/content": { "get": { "operationId": "messages.content", "summary": "Read a message's markdown content", "tags": [ "messages" ], "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": { "content_type": { "type": "string", "enum": [ "text/markdown" ] }, "content": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "content_type", "content", "version" ] } } } } } } }, "/api/v1/files/{id}/content": { "get": { "operationId": "files.content", "summary": "Download a file's bytes", "tags": [ "files" ], "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/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/identities/resolve": { "post": { "operationId": "identities.resolve", "summary": "Resolve addresses to identities, creating contacts for new ones", "tags": [ "identities" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 320 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "value" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "identities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "own": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "contact_id", "own", "created_by", "created_at", "updated_at" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "created_by", "created_at", "updated_at" ] }, "created": { "type": "boolean" } }, "required": [ "identity", "contact", "created" ] } } }, "required": [ "data" ] } } } } } } }, "/api/v1/contacts/{id}/merge": { "post": { "operationId": "contacts.merge", "summary": "Merge another contact into this one", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "contacts:request_approval" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid" } }, "required": [ "source_id" ], "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", "null" ] }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "merged_into_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_contacted_at": { "type": [ "string", "null" ], "description": "When the latest outbound interaction with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." }, "last_interacted_at": { "type": [ "string", "null" ], "description": "When the latest interaction, in either direction, with any of the contact's identities happened; null if none. Derived, read-only; present only with interactions:read." } }, "required": [ "id", "organization_id", "name", "company_id", "merged_into_id", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/messages/send": { "post": { "operationId": "messages.send", "summary": "Send plain-text email", "description": "Enqueued: answers 202 with the execution receipt; poll action_executions.get for the outcome. idempotency_key is required: repeating the call with the same key and arguments answers the same execution.", "tags": [ "messages" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": true, "request_scope": "messages:request_approval", "also_requires": "Reply requires messages:read. New mail needs no read scope. Connection credentials remain human-managed." }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "Active connected Gmail mailbox with read and send grants." }, "mode": { "type": "string", "enum": [ "new", "reply" ], "description": "new requires subject and forbids thread_id; reply requires thread_id and messages:read, forbids subject, and uses the authorised anchor." }, "thread_id": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "minLength": 1 }, "to": { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email" }, "maxItems": 50 }, "cc": { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email" }, "maxItems": 50 }, "body": { "type": "string", "description": "Plain text, at most 65536 UTF-8 bytes. Exact bytes are preserved; no attachments." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your key for this call: a repeat with the same key and arguments answers the same execution, and the same key with other arguments is 409 idempotency_key_reused. Unique per caller." } }, "required": [ "connection_id", "mode", "body", "idempotency_key" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "description": "The enqueued operation this executes, for example messages.send." }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed" ], "description": "queued (waiting or between attempts), claimed (an attempt is running), done or failed." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's final arguments, fixed when it was authorised." }, "action_request_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The approved action request this executes; null for a direct call." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that asked: the proposer for an approved request, the caller for a direct call." }, "authorised_by": { "type": "string", "format": "uuid", "description": "The principal whose authority it runs under: the approver, or the caller for a direct call." }, "idempotency_key": { "type": [ "string", "null" ], "description": "The caller's key of a direct call; null for an approved request." }, "result": { "description": "What the operation produced; null until done." }, "error_code": { "type": [ "string", "null" ], "description": "Why it failed: reauth_required, permission_missing, anchor_missing, provider_rejected, outcome_unknown, attempts_exhausted or deadline_passed." }, "error_message": { "type": [ "string", "null" ], "description": "The vault's sentence for the failure; never a provider's own text." }, "deadline_at": { "type": "string", "description": "When a never-attempted execution stops being attempted." }, "done_at": { "type": [ "string", "null" ], "description": "When it was executed: when it finished, done or failed; null while queued or claimed." }, "created_at": { "type": "string", "description": "When it was queued: the moment it was authorised. For an approved action request that is the approval, equal to the request's decided_at; for a direct call, the call." }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "status", "arguments", "action_request_id", "created_by", "authorised_by", "idempotency_key", "error_code", "error_message", "deadline_at", "done_at", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-requests": { "get": { "operationId": "action_requests.list", "summary": "List action_requests", "tags": [ "action_requests" ], "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": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": false, "name": "operation", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "created_by", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "decided_by", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "contact_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "thread_id", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "interaction_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "dedup_key", "in": "query" }, { "schema": { "type": "string", "enum": [ "id", "created_at", "updated_at", "expires_at", "decided_at" ], "description": "Sort by id or created_at or updated_at or expires_at or decided_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 expires_at or decided_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" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_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": "action_requests.create", "summary": "Propose a change for review", "description": "Proposes any proposal-eligible operation with its arguments; nothing changes until a reviewer approves. Needs :request_approval (or write) on the operation's resource, and the operation's own validation applies as for a direct call. Write-capable callers may propose too, to ask for review.", "tags": [ "action_requests" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "action requests are decided through action_requests.approve and action_requests.reject, never proposed" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "tasks.create", "tasks.update", "tasks.delete", "companies.create", "companies.update", "companies.delete", "contacts.create", "contacts.update", "contacts.delete", "identities.create", "identities.update", "identities.delete", "notes.create", "notes.update", "notes.delete", "tags.create", "tags.update", "tags.delete", "pipelines.create", "pipelines.update", "pipelines.delete", "pipeline_stages.create", "pipeline_stages.update", "pipeline_stages.delete", "deals.create", "deals.update", "deals.delete", "deals.move_stage", "associations.create", "associations.delete", "identities.resolve", "contacts.merge", "messages.send" ], "description": "The proposal-eligible operation to run on approval, for example tasks.update. Each operation's metadata (x-vault-proposal in OpenAPI) says what proposing it needs." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments: its path, query and body fields in one object, exactly as its MCP tool takes them." }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Why this change is proposed, plain text, for the reviewer." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false }, "maxItems": 20, "description": "Messages and interactions the proposal rests on." }, "contact_id": { "type": "string", "format": "uuid", "description": "Context: the contact this is about (needs contacts:read)." }, "thread_id": { "type": "string", "format": "uuid", "description": "Context: the thread this is about (needs messages:read)." }, "interaction_id": { "type": "string", "format": "uuid", "description": "Context: the interaction this is about (needs interactions:read); it must belong to thread_id when both are given." }, "dedup_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "At most one pending request per key: the same proposer replaces its earlier request, another proposer gets 409 duplicate_action_request." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the request stops being approvable; default 7 days, at most 30." } }, "required": [ "operation", "arguments", "reason" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-requests/{id}": { "get": { "operationId": "action_requests.get", "summary": "Get a action_request", "tags": [ "action_requests" ], "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" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-requests/{id}/withdraw": { "post": { "operationId": "action_requests.withdraw", "summary": "Withdraw a pending action request", "description": "Only the principal that proposed it can, while it is pending.", "tags": [ "action_requests" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "action requests are decided through action_requests.approve and action_requests.reject, never proposed" }, "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" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-requests/{id}/approve": { "post": { "operationId": "action_requests.approve", "summary": "Approve an action request and run its operation", "description": "Needs write on the operation's resource (a user or an agent). Runs the operation now, as you, on the request's arguments or your complete edited_arguments, in one step with the decision; if the operation refuses, you get its error and the request stays pending.", "tags": [ "action_requests" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "action requests are decided through action_requests.approve and action_requests.reject, never proposed" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "edited_arguments": { "type": "object", "additionalProperties": {}, "description": "Complete replacement arguments, validated and authorised as if proposed now. The original arguments stay on the request." }, "decision_reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-requests/{id}/reject": { "post": { "operationId": "action_requests.reject", "summary": "Reject an action request", "description": "Needs write on the operation's resource. The reason is feedback to the proposer.", "tags": [ "action_requests" ], "security": [ { "bearerAuth": [] } ], "x-vault-proposal": { "eligible": false, "reason": "action requests are decided through action_requests.approve and action_requests.reject, never proposed" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision_reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "description": "The registered operation proposed, for example tasks.update." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation." }, "edited_arguments": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The complete replacement arguments a reviewer approved instead; null unless approved with an edit." }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "expired", "superseded", "executed", "failed" ] }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message", "interaction" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "dedup_key": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" }, "decided_by": { "type": [ "string", "null" ], "format": "uuid", "description": "The principal (user or agent) that decided it; the system principal for an expiry." }, "decided_at": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] }, "superseded_by_id": { "type": [ "string", "null" ], "format": "uuid" }, "result": { "description": "What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution's result. Null until executed." }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The execution a queued approval created; absent or null until then and for operations that run inline." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that proposed it: the source." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "arguments", "edited_arguments", "status", "reason", "evidence", "contact_id", "thread_id", "interaction_id", "dedup_key", "expires_at", "decided_by", "decided_at", "decision_reason", "superseded_by_id", "error_code", "error_message", "executed_at", "created_by", "created_at", "updated_at" ] } } } } } } }, "/api/v1/action-executions": { "get": { "operationId": "action_executions.list", "summary": "List action executions", "description": "The durable executions of enqueued operations, oldest id first unless sorted (created_at is when one was queued, done_at when it was executed). You see an execution when you hold the read scope its operation declares (for example messages:read for messages.send); the list is empty otherwise.", "tags": [ "action_executions" ], "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": "string", "enum": [ "id", "created_at", "updated_at", "done_at" ], "description": "Sort by id or created_at or updated_at or done_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. For executions: created_at is queued at, the moment the execution was authorised (for an approved action request that is the approval, the request's decided_at, \"approved at\"; for a direct call, the call). done_at is executed at: when it finished, done or failed, and null while queued or claimed, so unfinished executions come first in asc and last in desc. The latest executed: sort=done_at&order=desc; the latest queued: sort=created_at&order=desc. updated_at moves only at creation and at the outcome, never between attempts." }, "required": false, "description": "Sort by id or created_at or updated_at or done_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. For executions: created_at is queued at, the moment the execution was authorised (for an approved action request that is the approval, the request's decided_at, \"approved at\"; for a direct call, the call). done_at is executed at: when it finished, done or failed, and null while queued or claimed, so unfinished executions come first in asc and last in desc. The latest executed: sort=done_at&order=desc; the latest queued: sort=created_at&order=desc. updated_at moves only at creation and at the outcome, never between attempts.", "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" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "claimed", "done", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": false, "name": "operation", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "action_request_id", "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" }, "operation": { "type": "string", "description": "The enqueued operation this executes, for example messages.send." }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed" ], "description": "queued (waiting or between attempts), claimed (an attempt is running), done or failed." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's final arguments, fixed when it was authorised." }, "action_request_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The approved action request this executes; null for a direct call." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that asked: the proposer for an approved request, the caller for a direct call." }, "authorised_by": { "type": "string", "format": "uuid", "description": "The principal whose authority it runs under: the approver, or the caller for a direct call." }, "idempotency_key": { "type": [ "string", "null" ], "description": "The caller's key of a direct call; null for an approved request." }, "result": { "description": "What the operation produced; null until done." }, "error_code": { "type": [ "string", "null" ], "description": "Why it failed: reauth_required, permission_missing, anchor_missing, provider_rejected, outcome_unknown, attempts_exhausted or deadline_passed." }, "error_message": { "type": [ "string", "null" ], "description": "The vault's sentence for the failure; never a provider's own text." }, "deadline_at": { "type": "string", "description": "When a never-attempted execution stops being attempted." }, "done_at": { "type": [ "string", "null" ], "description": "When it was executed: when it finished, done or failed; null while queued or claimed." }, "created_at": { "type": "string", "description": "When it was queued: the moment it was authorised. For an approved action request that is the approval, equal to the request's decided_at; for a direct call, the call." }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "status", "arguments", "action_request_id", "created_by", "authorised_by", "idempotency_key", "error_code", "error_message", "deadline_at", "done_at", "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" ] } } } } } } }, "/api/v1/action-executions/{id}": { "get": { "operationId": "action_executions.get", "summary": "Get an action execution", "description": "One execution: its status, arguments, who asked and who authorised it, and its result or classified failure. An execution you may not read is 404, as a missing one is.", "tags": [ "action_executions" ], "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" }, "operation": { "type": "string", "description": "The enqueued operation this executes, for example messages.send." }, "status": { "type": "string", "enum": [ "queued", "claimed", "done", "failed" ], "description": "queued (waiting or between attempts), claimed (an attempt is running), done or failed." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The operation's final arguments, fixed when it was authorised." }, "action_request_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The approved action request this executes; null for a direct call." }, "created_by": { "type": "string", "format": "uuid", "description": "The principal that asked: the proposer for an approved request, the caller for a direct call." }, "authorised_by": { "type": "string", "format": "uuid", "description": "The principal whose authority it runs under: the approver, or the caller for a direct call." }, "idempotency_key": { "type": [ "string", "null" ], "description": "The caller's key of a direct call; null for an approved request." }, "result": { "description": "What the operation produced; null until done." }, "error_code": { "type": [ "string", "null" ], "description": "Why it failed: reauth_required, permission_missing, anchor_missing, provider_rejected, outcome_unknown, attempts_exhausted or deadline_passed." }, "error_message": { "type": [ "string", "null" ], "description": "The vault's sentence for the failure; never a provider's own text." }, "deadline_at": { "type": "string", "description": "When a never-attempted execution stops being attempted." }, "done_at": { "type": [ "string", "null" ], "description": "When it was executed: when it finished, done or failed; null while queued or claimed." }, "created_at": { "type": "string", "description": "When it was queued: the moment it was authorised. For an approved action request that is the approval, equal to the request's decided_at; for a direct call, the call." }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "operation", "status", "arguments", "action_request_id", "created_by", "authorised_by", "idempotency_key", "error_code", "error_message", "deadline_at", "done_at", "created_at", "updated_at" ] } } } } } } } }, "webhooks": {} }