{ "openapi": "3.1.0", "info": { "title": "Micro Blocks API", "version": "2.0.0", "description": "Read and write objects, properties, lists, views, automations, and webhooks in a Micro workspace." }, "servers": [ { "url": "https://developers.micro.so", "description": "Production" } ], "paths": { "/v2/prism/{teamId}/{automationObjectType}/triggered_automations": { "post": { "summary": "Create a triggered automation (state + changeset filter trees)", "operationId": "createTriggeredAutomation", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "automationObjectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutomationObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } } } }, "responses": { "201": { "description": "Created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Automations" ] }, "get": { "summary": "List triggered automations for an owner", "operationId": "listTriggeredAutomations", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "automationObjectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutomationObjectType" } }, { "name": "list_id", "in": "query", "required": false, "description": "List (CRM) id to scope the listing to. When omitted, automations owned by the path team are returned.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "description": "Optional filter to a single automation kind. When omitted, both kinds are returned.", "schema": { "type": "string", "enum": [ "update", "lifecycle" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor (from a prior response's next_cursor); supersedes page/limit when present.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "deprecated": true, "description": "1-based page number. Prefer cursor.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum items per page (<= 50; defaults to 50).", "schema": { "type": "integer", "minimum": 0, "maximum": 50 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } }, "has_more": { "type": "boolean", "description": "True if more automations exist beyond this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null when has_more is false." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Automations" ] } }, "/v2/prism/{teamId}/{automationObjectType}/triggered_automations/{automationId}": { "get": { "summary": "Read a triggered automation", "operationId": "getTriggeredAutomation", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "automationObjectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutomationObjectType" } }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Automations" ] }, "put": { "summary": "Replace a triggered automation (idempotent full write of the whole tree)", "operationId": "putTriggeredAutomation", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "automationObjectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutomationObjectType" } }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggeredAutomationBundle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Automations" ] }, "delete": { "summary": "Delete a triggered automation and its filter trees", "operationId": "deleteTriggeredAutomation", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "automationObjectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutomationObjectType" } }, { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "No Content", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Automations" ] } }, "/v2/prism/{teamId}/{objectType}/{objectId}/restore": { "post": { "summary": "Restore object", "operationId": "restoreObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Object restored", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/{objectId}/duplicate": { "post": { "summary": "Duplicate object", "operationId": "duplicateObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Object duplicated. Returns the full new record (same shape as create).", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}": { "get": { "summary": "List records of an object type", "description": "Convenience list endpoint. Equivalent to `POST /v2/prism/{teamId}/{objectType}/query` with an empty body, plus query-string sugar for the common cases. Any unrecognized query parameter is interpreted as an equality filter on a property of that name; pass arrays for `in`. Values are received as strings, so non-string property filters via this endpoint may not work — use the `query` endpoint for typed comparisons or anything beyond simple equality.", "operationId": "listObjects", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`. Pass it back unchanged to fetch the next page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of rows to return. Capped server-side at 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "sort", "in": "query", "description": "Comma-separated list of slugs. Prefix with `-` for descending. Example: `sort=-updated_at,name`.", "schema": { "type": "string" } }, { "name": "select", "in": "query", "description": "Comma-separated property slugs to return. Use dot notation for relationships. `id` is always returned at the top level. Defaults to all properties.", "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "description": "Scope properties to a specific list/app.", "schema": { "type": "string", "format": "uuid" } }, { "name": "deleted", "in": "query", "description": "Include soft-deleted records. Pass the literal string `true`.", "schema": { "type": "boolean" } }, { "name": "include_total", "in": "query", "description": "When set to `true`, the response includes a `total` field with the unpaginated row count. Costs an extra pass; prefer `GET .../count` for the unfiltered total.", "schema": { "type": "boolean" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of records.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrismQueryRow" } }, "has_more": { "type": "boolean", "description": "Accurate end-of-data signal — false on the last page, never forces clients to overshoot." }, "next_cursor": { "type": [ "string", "null" ] }, "total": { "type": [ "integer", "null" ], "description": "Populated only when `?include_total=true` was passed." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Records" ] }, "post": { "summary": "Create object", "description": "Creates a record. For `document`, writing `content` (or HTML) stores the property and reads back, but the in-app editor is CRDT-backed and will render a blank page until that document has been opened and saved in the app. Treat API-created docs as data records, not as collaboratively edited pages, unless you only need the stored property values.", "operationId": "createObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectProperties" }, "examples": { "contact": { "summary": "Contact example", "value": { "default": { "full_name": "Sarah Chen", "email": "sarah@example.com", "title": "Partner", "organization": "Acme Ventures" } } }, "organization": { "summary": "Organization example", "value": { "default": { "name": "Acme Ventures", "domain": "example.com", "industry": "Venture Capital" } } }, "deal": { "summary": "Deal example", "value": { "default": { "name": "Acme Ventures — Series A", "amount": 2500000, "stage": "negotiation", "organization": "Acme Ventures" } } }, "action": { "summary": "Action example", "value": { "default": { "name": "Follow up with Sarah Chen", "status": "open", "due_date": "2026-08-06", "contact": "Sarah Chen" } } }, "document": { "summary": "Document example", "value": { "default": { "name": "Acme Ventures — Series A notes", "content": "Sarah Chen is coordinating diligence for the Series A.", "organization": "Acme Ventures" } } } } } } }, "responses": { "201": { "description": "Object created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" }, "examples": { "contact": { "summary": "Contact example", "value": { "id": "11111111-1111-4111-8111-111111111111", "default": { "full_name": "Sarah Chen", "email": "sarah@example.com", "title": "Partner", "organization": "Acme Ventures" } } }, "organization": { "summary": "Organization example", "value": { "id": "22222222-2222-4222-8222-222222222222", "default": { "name": "Acme Ventures", "domain": "example.com", "industry": "Venture Capital" } } }, "deal": { "summary": "Deal example", "value": { "id": "33333333-3333-4333-8333-333333333333", "default": { "name": "Acme Ventures — Series A", "amount": 2500000, "stage": "negotiation", "organization": "Acme Ventures" } } }, "action": { "summary": "Action example", "value": { "id": "44444444-4444-4444-8444-444444444444", "default": { "name": "Follow up with Sarah Chen", "status": "open", "due_date": "2026-08-06", "contact": "Sarah Chen" } } }, "document": { "summary": "Document example", "value": { "id": "55555555-5555-4555-8555-555555555555", "default": { "name": "Acme Ventures — Series A notes", "content": "Sarah Chen is coordinating diligence for the Series A.", "organization": "Acme Ventures" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/by/{slug}/{value}": { "get": { "summary": "Find a record by property value", "description": "Returns the single record whose property `{slug}` equals `{value}`. 404 if nothing matches; 409 if more than one record matches.", "operationId": "findObjectBySlug", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "slug", "in": "path", "required": true, "description": "Property slug to match (e.g. `email`).", "schema": { "type": "string" } }, { "name": "value", "in": "path", "required": true, "description": "Property value to match exactly. URL-encode special characters.", "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "description": "Scope the lookup to a specific list/app.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Matched record", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Records" ] }, "put": { "summary": "Upsert by property value", "description": "Idempotent create-or-update keyed on `{slug}={value}`. If exactly one record matches, it is patched and 200 is returned. If none match, a new record is created (with the lookup property set if absent) and 201 is returned. If multiple records match, 409 is returned and you should patch by id instead.", "operationId": "upsertObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "value", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "description": "Scope the upsert to a specific list/app. Required to match or write list-scoped properties, including `app_stage`.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectProperties" } } } }, "responses": { "200": { "description": "Existing record patched.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" } } } }, "201": { "description": "New record created.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/{objectId}": { "get": { "summary": "Get object", "operationId": "getObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "select", "in": "query", "description": "Comma-separated property slugs to return. Use dot notation for relationships. `id` is always returned at the top level. Defaults to all properties.", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" }, "examples": { "contact": { "summary": "Contact example", "value": { "id": "11111111-1111-4111-8111-111111111111", "default": { "full_name": "Sarah Chen", "email": "sarah@example.com", "title": "Partner", "organization": "Acme Ventures" } } }, "organization": { "summary": "Organization example", "value": { "id": "22222222-2222-4222-8222-222222222222", "default": { "name": "Acme Ventures", "domain": "example.com", "industry": "Venture Capital" } } }, "deal": { "summary": "Deal example", "value": { "id": "33333333-3333-4333-8333-333333333333", "default": { "name": "Acme Ventures — Series A", "amount": 2500000, "stage": "negotiation", "organization": "Acme Ventures" } } }, "action": { "summary": "Action example", "value": { "id": "44444444-4444-4444-8444-444444444444", "default": { "name": "Follow up with Sarah Chen", "status": "open", "due_date": "2026-08-06", "contact": "Sarah Chen" } } }, "document": { "summary": "Document example", "value": { "id": "55555555-5555-4555-8555-555555555555", "default": { "name": "Acme Ventures — Series A notes", "content": "Sarah Chen is coordinating diligence for the Series A.", "organization": "Acme Ventures" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Records" ] }, "delete": { "summary": "Delete object", "operationId": "deleteObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "Object soft-deleted. Use the restore endpoint within the retention window to undo.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Records" ] }, "patch": { "summary": "Patch object", "operationId": "patchObject", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectProperties" }, "examples": { "contact": { "summary": "Contact example", "value": { "default": { "title": "General Partner" } } }, "organization": { "summary": "Organization example", "value": { "default": { "domain": "acme.example.com" } } }, "deal": { "summary": "Deal example", "value": { "default": { "stage": "closed_won" } } }, "action": { "summary": "Action example", "value": { "default": { "status": "completed" } } }, "document": { "summary": "Document example", "value": { "default": { "content": "Sarah Chen confirmed the next diligence call." } } } } } } }, "responses": { "200": { "description": "Object updated", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismObjectResponse" }, "examples": { "contact": { "summary": "Contact example", "value": { "id": "11111111-1111-4111-8111-111111111111", "default": { "full_name": "Sarah Chen", "email": "sarah@example.com", "title": "General Partner", "organization": "Acme Ventures" } } }, "organization": { "summary": "Organization example", "value": { "id": "22222222-2222-4222-8222-222222222222", "default": { "name": "Acme Ventures", "domain": "acme.example.com", "industry": "Venture Capital" } } }, "deal": { "summary": "Deal example", "value": { "id": "33333333-3333-4333-8333-333333333333", "default": { "name": "Acme Ventures — Series A", "amount": 2500000, "stage": "closed_won", "organization": "Acme Ventures" } } }, "action": { "summary": "Action example", "value": { "id": "44444444-4444-4444-8444-444444444444", "default": { "name": "Follow up with Sarah Chen", "status": "completed", "due_date": "2026-08-06", "contact": "Sarah Chen" } } }, "document": { "summary": "Document example", "value": { "id": "55555555-5555-4555-8555-555555555555", "default": { "name": "Acme Ventures — Series A notes", "content": "Sarah Chen confirmed the next diligence call.", "organization": "Acme Ventures" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/{objectId}/grant": { "get": { "summary": "Get grant", "operationId": "getGrant", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Sharing" ] }, "put": { "summary": "Update grant", "operationId": "updateGrant", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantObjectType" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRequest" } } } }, "responses": { "200": { "description": "Grant updated", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Sharing" ] } }, "/v2/prism/{teamId}/{objectType}/query": { "post": { "summary": "Query", "operationId": "query", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" }, "description": "Queryable object type. Same set as `ObjectType` (CRUD). `GET /v2/prism/{teamId}/properties` also returns metadata for pipeline-owned types such as `message` that are not in this set and cannot be queried. Contacts expose `last_email` as a `ref_message`; you cannot follow it with a `message` query." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "object", "required": [ "select" ], "properties": { "select": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Property slugs to select. Use dot notation for relationships (e.g. attendee.contact.first_name). `id` is always returned at the top level of each row and does not need to be selected." }, "filter": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "object", "minProperties": 1, "maxProperties": 1, "propertyNames": { "enum": [ "=", "!=", "<", ">", "<=", ">=", "contains", "begins_with", "ends_with", "not_contains", "exists", "not_exists", "is_null", "is_not_null", "between", "in", "not_in" ], "description": "`between` takes a two-element [min, max] array (inclusive on both ends). `is_null` / `is_not_null` are aliases for `not_exists` / `exists` and take any truthy value." }, "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } }, "description": "Filters as [{ slug: { operator: value } }]. For select/multiselect properties, values may be option slugs or option UUIDs." }, "sort": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, "description": "Sort order as [{ slug: direction }]. Array order determines sort priority" }, "combinator": { "type": "string", "description": "Logical operator for combining filters", "enum": [ "AND", "OR" ], "default": "AND" }, "list_id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "description": "Opaque cursor from a previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When set, `page` and `limit` are derived from the cursor and any explicit values are ignored." }, "page": { "type": "integer", "deprecated": true, "description": "Page number (1-based). Prefer `cursor`. Page-number pagination drifts under concurrent writes; use it only for one-shot exports." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of rows to return. Capped server-side at 50; requests above the cap are rejected." } }, "additionalProperties": false }, "cursor": { "type": "string", "description": "Alternative location for the opaque cursor (a sibling of `query`). Use whichever feels more natural; if both are present, `query.cursor` wins." }, "include_total": { "type": "boolean", "description": "When true, the response includes a `total` field with the unpaginated row count. Costs an additional pass over the result set — for unfiltered totals prefer `GET /v2/prism/{teamId}/{objectType}/count` instead.", "default": false }, "id": { "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "deleted": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "boxes": { "type": "array", "items": { "type": "string" } } } }, "examples": { "contact": { "summary": "Contact example", "value": { "query": { "select": [ "full_name", "email", "title", "organization" ], "filter": [ { "full_name": { "=": "Sarah Chen" } } ], "limit": 10 }, "include_total": true } } } } } }, "responses": { "200": { "description": "Successful query", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrismQueryRow" } }, "has_more": { "type": "boolean", "description": "Accurate end-of-data signal. False when this page contains the last record; true only when at least one more record exists. (Implementation note: the server fetches one extra row internally to determine this — clients never need to overshoot to discover the end.)" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor pointing at the next page. Pass it back unchanged. Do not parse it. The current encoding is offset-based (page + limit), so it has the same concurrent-write drift the deprecated `page` parameter has; treat it as a black box so a future keyset cursor is a drop-in. Null when `has_more` is false." }, "total": { "type": [ "integer", "null" ], "description": "Only populated when the request set `include_total: true`. Total number of records matching the query, ignoring pagination. Opt-in because it costs an additional pass over the result set." } } }, "examples": { "contact": { "summary": "Contact example", "value": { "data": [ { "id": "11111111-1111-4111-8111-111111111111", "properties": { "full_name": "Sarah Chen", "email": "sarah@example.com", "title": "Partner", "organization": "Acme Ventures" }, "is_user_object": false, "source": null } ], "has_more": false, "next_cursor": null, "total": 1 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Query" ] } }, "/v2/prism/{teamId}/lists": { "post": { "summary": "Create a list (app/CRM)", "description": "Creates a list from a template. Seeds properties, pipeline stages (when applicable), and default views — identical to the session-auth `/default_app/create` path. API-key callers are fully supported; `type` is derived from `template_id` and must not be supplied.", "operationId": "createList", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreate" } } } }, "responses": { "201": { "description": "The created list, including seeded view ids when the template ships any.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Lists" ] }, "get": { "summary": "List apps/CRMs in a workspace", "description": "Returns non-core lists the caller can access in the workspace. Core system apps (Messages, All Inbox) are excluded.", "operationId": "listLists", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Accessible lists.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Lists" ] } }, "/v2/prism/{teamId}/lists/{listId}": { "get": { "summary": "Get a list by id", "operationId": "getList", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The list.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Lists" ] } }, "/v2/prism/{teamId}/properties": { "get": { "summary": "Get metadata properties", "description": "Lists property definitions across every object type the engine knows about, including pipeline-owned types that are not queryable or CRUD-capable (`message`, `thread`, `linkedin_thread`, and others). Only the `ObjectType` enum (12 types) can be queried, created, updated, or listed. Contacts point at `message` via `last_email`; that relationship cannot be followed with `/query`.", "operationId": "getMetadataProperties", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "list_id", "in": "query", "description": "Scope properties to a specific list/app. Scoping is strict: the response carries only that list's definitions, not the workspace-global ones that also apply to its records. Call once with `list_id` and once without to see everything a write could resolve against.", "schema": { "type": "string", "format": "uuid" } }, { "name": "autofill", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_options", "in": "query", "description": "When false, return property definitions without hydrating select/multiselect option rows. Defaults to true server-side (parseIncludeOptions). Accepts boolean or query-string forms (true/false/0/1). Uses anyOf (not oneOf) so qs/AJV boolean-vs-string ambiguity does not 400 when Speakeasy SDKs send include_options=true.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false", "0", "1" ] } ] } }, { "name": "term", "in": "query", "description": "Case-insensitive substring match on the property name. Use this to find an existing property before creating a new one.", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataPropertiesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Data model" ] } }, "/v2/prism/{teamId}/{objectType}/count": { "get": { "summary": "Total record count for an object type", "description": "Returns the total number of records of this object type that the caller can see. Avoids the page-overshoot anti-pattern — clients no longer need to keep paging until `has_more` flips false to discover the total. Currently does not apply query filters; for a filtered total, pass `include_total: true` in a POST `/query` body. Unfiltered counts on high-cardinality types (especially `engagement`) scan the full access-scoped set and can take tens of seconds or time out; prefer a filtered `include_total` query or accept that this endpoint is expensive there.", "operationId": "countObjects", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "list_id", "in": "query", "description": "Scope the count to a specific list/app.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "total" ], "properties": { "total": { "type": "integer", "description": "Number of records matching the access scope." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Query" ] } }, "/v2/prism/{teamId}/{objectType}/properties": { "get": { "summary": "Get metadata properties by object type", "operationId": "getMetadataPropertiesByObjectType", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "list_id", "in": "query", "description": "Scope properties to a specific list/app. Scoping is strict: the response carries only that list's definitions, not the workspace-global ones that also apply to its records. Call once with `list_id` and once without to see everything a write could resolve against.", "schema": { "type": "string", "format": "uuid" } }, { "name": "autofill", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_options", "in": "query", "description": "When false, return property definitions without hydrating select/multiselect option rows. Defaults to true server-side (parseIncludeOptions). Accepts boolean or query-string forms (true/false/0/1). Uses anyOf (not oneOf) so qs/AJV boolean-vs-string ambiguity does not 400 when Speakeasy SDKs send include_options=true.", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false", "0", "1" ] } ] } }, { "name": "term", "in": "query", "description": "Case-insensitive substring match on the property name. Use this to find an existing property before creating a new one.", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataPropertiesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Data model" ] }, "post": { "summary": "Create a property definition", "description": "Define a new property on this object type, scoped to the calling team. Search the existing properties first (GET this path with `term`) and reuse a match instead of defining a second property for the same fact. Pass `list_id` in the body to scope the definition to one list/app; without it the property is workspace-global and appears on every list. A name already used in that scope, an explicitly requested slug already taken, or a slug that a shared property already owns all return 409 naming the definition to use instead. The property's display format is resolved from `type` automatically — pass `role_id` only to override it. For `select_str` and `multiselect_str` types you may pre-seed the choices via `options`.", "operationId": "createMetadataProperty", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyDefinitionCreate" } } } }, "responses": { "201": { "description": "Property created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Data model" ] } }, "/v2/prism/{teamId}/{objectType}/properties/{propertyId}": { "patch": { "summary": "Update a property definition", "description": "Patches the editable fields (`name`, `icon`, `enabled`) of a property definition. `type` and scoping fields are immutable; `type` must be supplied in the body so the server knows which per-type table to write.", "operationId": "patchMetadataProperty", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyDefinitionPatch" } } } }, "responses": { "200": { "description": "Property updated", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyDefinition" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Data model" ] }, "delete": { "summary": "Delete a property definition", "description": "Removes the property definition and any of its options. Fails with 409 `property_in_use` if records still reference the property.", "operationId": "deleteMetadataProperty", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": true, "description": "Storage type of this property definition.", "schema": { "$ref": "#/components/schemas/PropertyType" } }, { "name": "list_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "Deleted", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Data model" ] } }, "/v2/prism/{teamId}/{objectType}/properties/{propertyId}/options": { "post": { "summary": "Add an option to a select property", "description": "Adds a single option to a `select_str` or `multiselect_str` property definition. Body must include `type` so the server knows which per-type option table to write.", "operationId": "createMetadataPropertyOption", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/OptionPropertyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyOptionCreate" } } } }, "responses": { "201": { "description": "Option created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyOption" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Data model" ] } }, "/v2/prism/{teamId}/{objectType}/properties/{propertyId}/options/{optionId}": { "patch": { "summary": "Update a property option", "operationId": "patchMetadataPropertyOption", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/OptionPropertyId" }, { "name": "optionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyOptionPatch" } } } }, "responses": { "200": { "description": "Option updated", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyOption" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Data model" ] }, "delete": { "summary": "Delete a property option", "operationId": "deleteMetadataPropertyOption", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/OptionPropertyId" }, { "name": "optionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PropertyType" } }, { "name": "list_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "Deleted", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Data model" ] } }, "/v2/prism/{teamId}/{objectType}/batch/update": { "post": { "summary": "Bulk update records (partial success)", "description": "Patch up to 100 records in a single call. Each item is attempted independently — failures don't abort the batch. Inspect `results[].status` per item.", "operationId": "batchUpdateObjects", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "description": "Object with `id` plus the same property body shape as PATCH (`default`/`list`/`extended`).", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Per-item outcomes", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/batch/delete": { "post": { "summary": "Bulk delete records (partial success)", "description": "Soft-delete up to 100 records in a single call. Same partial-success contract as batch/update.", "operationId": "batchDeleteObjects", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Per-item outcomes", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Records" ] } }, "/v2/prism/{teamId}/{objectType}/sharing-summary": { "post": { "summary": "Get sharing summary for multiple objects", "description": "Returns per-object sharing flags for ids the caller can read. Objects the caller cannot read are omitted.", "operationId": "getSharingSummary", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Sharing summary keyed by object id", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "required": [ "isShared", "canManageSharing" ], "properties": { "isShared": { "type": "boolean" }, "canManageSharing": { "type": "boolean" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Sharing" ] } }, "/v2/prism/{teamId}/imports/{jobId}": { "get": { "summary": "Get the status of an import job", "description": "Poll the status of an async import. Sync imports complete in the original response and don't appear here. Async jobs are retained for 7 days. Returns 404 once the job has expired.", "operationId": "getImportJob", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "jobId", "in": "path", "required": true, "description": "The `job_id` returned from POST /import.", "schema": { "type": "string" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Current job state", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Imports" ] } }, "/v2/prism/{teamId}/{objectType}/import": { "post": { "summary": "Import objects", "description": "Import multiple objects in batch. Properties are keyed by slug. Automatically routes based on size: small batches complete synchronously and return 200 with the final `ImportJob`; large batches start an async job, return 202 with `status: processing` and a `Location` header, and can be polled via `GET /v2/prism/{teamId}/imports/{jobId}`.", "operationId": "importObjects", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ImportObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } }, "responses": { "200": { "description": "Import complete (sync path for small batches). `status` is `complete`, `job_id` is null, and per-row outcomes are inlined under `results`.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "202": { "description": "Import accepted for async processing. Poll `GET /v2/prism/{teamId}/imports/{job_id}` (also available via the `Location` header) until `status` is `complete` or `failed`.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "metered" }, "tags": [ "Imports" ] } }, "/v2/prism/{teamId}/{objectType}/views": { "post": { "summary": "Create a view bundle (view + select/filter/sort)", "operationId": "createView", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewBundle" } } } }, "responses": { "201": { "description": "Created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewBundle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Views" ] }, "get": { "summary": "List saved views for an owner", "description": "Returns saved view bundles for the path team. Pass `?list_id=` to scope to a list (CRM) instead. Cursor pagination matches other Prism list endpoints.", "operationId": "listViews", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "list_id", "in": "query", "required": false, "description": "List (CRM) id to scope the listing to. When omitted, views owned by the path team are returned.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor (from a prior response's next_cursor); supersedes page/limit when present.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "deprecated": true, "description": "1-based page number. Prefer cursor.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum items per page (<= 50; defaults to 50).", "schema": { "type": "integer", "minimum": 0, "maximum": 50 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ViewBundle" } }, "has_more": { "type": "boolean", "description": "True if more views exist beyond this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null when has_more is false." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Views" ] } }, "/v2/prism/{teamId}/{objectType}/views/{viewId}": { "get": { "summary": "Read a view bundle", "description": "Returns the view bundle. Pass `?include=records` to also fetch a page of records selected by the view in the same call; the response is then wrapped as `{view, records}`.", "operationId": "getView", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of optional sub-resources to inline. Currently the only recognized value is `records` — when present, the response is `{view, records}` rather than the bare view bundle.", "schema": { "type": "string", "example": "records" } }, { "name": "cursor", "in": "query", "required": false, "description": "Forwarded to the records sub-resource when `include=records`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "deprecated": true, "description": "Forwarded to the records sub-resource when `include=records`.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Forwarded to the records sub-resource when `include=records`.", "schema": { "type": "integer", "minimum": 0, "maximum": 50 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK. Returns the view bundle by default; returns `{view, records}` when `include=records` is passed.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ViewBundle" }, { "$ref": "#/components/schemas/ViewBundleWithRecords" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Views" ] }, "patch": { "summary": "Update a view bundle (select/filter/sort arrays are replaced wholesale when supplied)", "operationId": "patchView", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewBundlePatch" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "etag": { "$ref": "#/components/headers/ETag" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewBundle" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Views" ] }, "delete": { "summary": "Delete a view bundle", "operationId": "deleteView", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "View deleted", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Views" ] } }, "/v2/prism/{teamId}/{objectType}/views/{viewId}/records": { "get": { "summary": "List records selected by a view (filters and sorts applied; pinned record_order overlaid first)", "operationId": "listViewRecords", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When set, `page` and `limit` are derived from the cursor.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "deprecated": true, "description": "Page number (1-based). Prefer `cursor`.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 50 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "has_more": { "type": "boolean", "description": "True if more records exist beyond this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null when `has_more` is false." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Views" ] }, "patch": { "summary": "Bulk reorder pinned records", "operationId": "reorderViewRecords", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordOrderUpdate" } } } }, "responses": { "204": { "description": "Records reordered", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Views" ] } }, "/v2/prism/{teamId}/{objectType}/views/{viewId}/records/{objectId}": { "post": { "summary": "Pin a record to the view (append to record_order)", "operationId": "pinViewRecord", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Pinned", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "idempotent-replay": { "$ref": "#/components/headers/IdempotentReplay" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "write", "idempotent": true, "confirmation": "recommended", "cost": "free" }, "tags": [ "Views" ] }, "delete": { "summary": "Unpin a record from the view", "operationId": "unpinViewRecord", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ViewObjectType" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "Record unpinned", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Views" ] } }, "/v2/webhooks/{teamId}": { "get": { "summary": "List webhooks", "description": "Lists the team's webhooks. Signing secrets are never included.", "operationId": "listWebhooks", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The team's webhooks.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Webhooks" ] }, "post": { "summary": "Create a webhook", "description": "Registers a webhook and enqueues an asynchronous verification handshake (run by the dispatcher). The response includes the signing `secret`, shown only this once; `verified` is false until the handshake passes.", "operationId": "createWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "The created webhook, including its one-time signing secret.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-micro-safety": { "class": "write", "idempotent": false, "confirmation": "recommended", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/{webhookId}": { "get": { "summary": "Get a webhook", "operationId": "getWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The webhook.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Webhooks" ] }, "patch": { "summary": "Update a webhook", "description": "Updates mutable fields. Changing `url` resets verification and re-runs the handshake.", "operationId": "updateWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "The updated webhook.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithVerification" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-micro-safety": { "class": "write", "idempotent": false, "confirmation": "recommended", "cost": "free" }, "tags": [ "Webhooks" ] }, "delete": { "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "Deleted.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "destructive", "idempotent": false, "confirmation": "required", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/{webhookId}/verify": { "post": { "summary": "Re-run verification", "description": "Re-runs the GET challenge/echo handshake against the webhook's url and updates its verified state.", "operationId": "verifyWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The webhook, with a pending verification status (the handshake runs asynchronously).", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithVerification" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "write", "idempotent": false, "confirmation": "recommended", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/{webhookId}/ping": { "post": { "summary": "Send a test event", "description": "Fire-and-forget test delivery through the async dispatcher. The webhook must be enabled and verified.", "operationId": "pingWebhook", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPingRequest" } } } }, "responses": { "202": { "description": "Event accepted for asynchronous delivery.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPingResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "write", "idempotent": false, "confirmation": "recommended", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/deliveries": { "get": { "summary": "List team deliveries", "description": "Account-wide delivery feed across all of the team's webhooks, newest first.", "operationId": "listTeamWebhookDeliveries", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by outcome.", "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "type", "in": "query", "description": "Filter by run type. Defaults to `delivery` (event deliveries). Pass `all` to include verification handshakes.", "schema": { "type": "string", "enum": [ "delivery", "verification", "all" ] } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of deliveries.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/{webhookId}/deliveries": { "get": { "summary": "List webhook deliveries", "description": "An endpoint's deliveries, newest first, with optional status / type / time-range filters and cursor pagination.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by outcome.", "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "type", "in": "query", "description": "Filter by run type. Defaults to `delivery` (event deliveries). Pass `all` to include verification handshakes.", "schema": { "type": "string", "enum": [ "delivery", "verification", "all" ] } }, { "name": "before", "in": "query", "description": "Only deliveries at or before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "after", "in": "query", "description": "Only deliveries at or after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (1–100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of deliveries.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/webhooks/{teamId}/{webhookId}/deliveries/{deliveryId}": { "get": { "summary": "Get a delivery", "description": "A single delivery plus its full attempt timeline (including async retries).", "operationId": "getWebhookDelivery", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The delivery and its attempts.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Webhooks" ] } }, "/v2/realtime/ticket": { "post": { "summary": "Create a realtime streaming ticket", "description": "Exchange your API key (or session) for a short-lived ticket that authenticates a connection to the realtime object-change stream. Open a WebSocket to the push endpoint with the returned ticket as the `token` query parameter. The ticket is single-purpose and expires quickly; call this again to obtain a fresh one before reconnecting.", "operationId": "createRealtimeTicket", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeTicket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-micro-safety": { "class": "read", "idempotent": true, "confirmation": "none", "cost": "free" }, "tags": [ "Realtime" ] } } }, "components": { "schemas": { "List": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "object_type", "team_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "icon": { "type": [ "string", "null" ], "description": "Emoji or icon key for the list." }, "object_type": { "type": "string", "enum": [ "organization", "identity", "action", "document", "deal" ], "description": "Prism object type this list holds." }, "type": { "type": [ "string", "null" ], "description": "Internal template type (e.g. dealFlow, hiring). Derived from template_id on create." }, "team_id": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "views": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } } } } } }, "ListCreate": { "type": "object", "additionalProperties": false, "required": [ "template_id" ], "properties": { "template_id": { "type": "string", "enum": [ "sales_deals", "recruiting", "partnerships", "fundraising", "knowledge_base", "issue_tracker", "content_calendar", "job_applications", "project_tracker", "feedback", "portco_tracker", "deal_flow", "lp_fundraising", "custom" ], "description": "Template to seed the list from. `type` is derived server-side from this template." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "icon": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Emoji or icon override." }, "object_type": { "type": "string", "enum": [ "organization", "identity", "action", "document", "deal" ], "description": "Required only when template_id is `custom`." } } }, "ListCollection": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/List" } } } }, "TriggeredAutomationAction": { "type": "object", "description": "An action the automation runs when it fires. `type` selects the kind; the remaining fields are type-specific (`agent` → `agent_id`, `webhook` → `webhook_id`, `email`/`linkedin` → the send-as user, template, and recipient-view fields). Generic: new action types add fields here.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "agent", "webhook", "wait", "email", "linkedin" ] }, "agent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `agent`. The agent to run." }, "webhook_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `webhook`. The id of the webhook the event is dispatched to (async) when the automation fires." }, "delay_seconds": { "type": [ "integer", "null" ], "description": "wait: relative delay in seconds. Exactly one of delay_seconds or cron_expression." }, "cron_expression": { "type": [ "string", "null" ], "description": "wait: cron schedule for the resume time. Exactly one of delay_seconds or cron_expression." }, "timezone": { "type": [ "string", "null" ], "description": "wait: IANA timezone for evaluating cron_expression (optional)." }, "send_as_user_id": { "type": [ "string", "null" ], "description": "Required when `type` is `email` or `linkedin`. The user (external id) the message is sent as." }, "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `email` or `linkedin`. The email-template document whose body is rendered (Liquid) per recipient." }, "subject": { "type": [ "string", "null" ], "description": "Required when `type` is `email`. The subject line; rendered as a Liquid template per recipient." }, "recipient_view_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `email` or `linkedin`. The saved prism view resolved at send time to the recipient audience (its filter re-runs each step, so responders drop out of later drip sends)." }, "recipient_view_object_type": { "type": [ "string", "null" ], "description": "Required when `type` is `email` or `linkedin`. Must be `contact` — the recipient audience is a contact view (contacts carry the direct email / linkedin provider property)." }, "recipient_email_prop_def_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `email`. The property (on the recipient view object) holding the recipient email address." }, "recipient_provider_prop_def_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Required when `type` is `linkedin`. The property (on the recipient view object) holding the recipient LinkedIn provider id." } }, "additionalProperties": true }, "TriggeredAutomationFilterGroup": { "type": "object", "description": "A filter group: a combinator plus an array of slug-based clauses. Dot-paths (e.g. `organization.location`) express nested reference filters.", "properties": { "combinator": { "type": "string", "enum": [ "AND", "OR" ] }, "filter": { "type": "array", "description": "Each entry is { slug: { comparator: value } }", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": false }, "TriggeredAutomationChangesetGroup": { "type": "object", "description": "A changeset filter group (update automations only): a combinator plus an array of transition clauses matching what is changing. Dot-paths (nested reference filters) are NOT permitted — direct properties only.", "properties": { "combinator": { "type": "string", "enum": [ "AND", "OR" ] }, "filter": { "type": "array", "description": "Each entry is a transition clause { slug: { from?: { comparator: value }, to?: { comparator: value } } }. `from` matches the prior value, `to` the new value; an empty body { slug: {} } matches any change to that property.", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": false }, "TriggeredAutomationBundle": { "type": "object", "description": "A triggered automation. `kind` selects the shape: `update` fires on object updates and requires a `changeset` (from/to transition) filter plus an optional `state` precondition; `lifecycle` fires on create and/or delete (`on_create`/`on_delete`) and requires a `state` filter (no changeset). `state` permits dot-paths (nested reference filters); `changeset` is direct properties only. Object type is taken from the path.", "required": [ "name", "kind" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "update", "lifecycle" ] }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "on_create": { "type": "boolean", "description": "Lifecycle automations only." }, "on_delete": { "type": "boolean", "description": "Lifecycle automations only." }, "state": { "$ref": "#/components/schemas/TriggeredAutomationFilterGroup" }, "changeset": { "$ref": "#/components/schemas/TriggeredAutomationChangesetGroup" }, "actions": { "type": "array", "description": "Actions to run when the automation fires; each item has a `type` plus type-specific fields.", "items": { "$ref": "#/components/schemas/TriggeredAutomationAction" } }, "created_at": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ImportJob": { "type": "object", "description": "Status snapshot of an import job. Same shape used by the POST /import response and by GET /imports/{jobId}.", "required": [ "job_id", "status", "total" ], "properties": { "job_id": { "type": [ "string", "null" ], "description": "Null for sync imports (results inlined). Set for async imports." }, "status": { "type": "string", "enum": [ "complete", "processing", "failed" ] }, "total": { "type": "integer", "description": "Total number of rows in the import." }, "processed": { "type": "integer", "description": "Rows that have been attempted (succeeded + failed)." }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "description": "Per-row outcomes. Always present for sync imports; populated for async imports once the job reaches `complete`.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "created": { "type": "boolean" }, "existing": { "type": "boolean", "description": "True if the row matched an existing record via the dedupe key." }, "updated": { "type": "boolean", "description": "True if a matching record was updated." }, "input_index": { "type": "integer", "minimum": 0, "description": "Zero-based position of this row in the request." }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "error": { "type": "object", "description": "Set when status=failed; describes the job-level failure (not per-row).", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "BatchResult": { "type": "object", "required": [ "results", "summary" ], "description": "Partial-success bulk operation result. Inspect `results[].status` per item; the operation as a whole returns 200 even if some items failed.", "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Item ID, or null if the input was unparseable." }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "record": { "$ref": "#/components/schemas/PrismObjectResponse" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "summary": { "type": "object", "required": [ "total", "succeeded", "failed" ], "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "Error": { "type": "object", "description": "Canonical JSON error envelope for every non-2xx v2 API response. `error.code` is the machine-readable error code, `error.message` is the human-readable summary, and `error.request_id` identifies the request for support. When supplied, `error.errors` contains field-level validation issues.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the HTTP status, to handle specific failure modes.", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable summary suitable for logs. Not localized; do not display verbatim to end users." }, "request_id": { "type": [ "string", "null" ], "description": "Echo of the x-request-id response header. Include in support requests." }, "errors": { "type": "array", "description": "Optional structured field-level validation issues when the server provides them.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "JSON path of the offending property (e.g. \".body.default.email\")." }, "message": { "type": "string" }, "code": { "type": "string", "description": "Validator-specific code (e.g. \"required.openapi.validation\")." } }, "required": [ "message" ] } }, "details": { "type": "object", "description": "Optional bag of error-specific context. Shape varies by code; clients should treat fields as opaque unless documented." } } } } }, "PrismObjectProperties": { "type": "object", "properties": { "extended": { "type": "object", "minProperties": 1 }, "default": { "type": "object", "description": "Properties keyed by property slug. Values can be strings, numbers, booleans, arrays, or null. For select/multiselect properties, values may be option slugs or option UUIDs on write; option slugs are returned on read.", "minProperties": 1, "additionalProperties": {} }, "list": { "type": "object", "minProperties": 1, "patternProperties": { "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": { "type": "object", "description": "Properties keyed by property slug", "minProperties": 1, "additionalProperties": {} } }, "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "default" ] }, { "required": [ "list" ] } ] }, "PrismObjectResponse": { "type": "object", "description": "Object returned by reads (get/create/patch/restore). id is always present.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "extended": { "type": "object" }, "default": { "type": "object", "description": "Properties keyed by property slug.", "additionalProperties": {} }, "list": { "type": "object", "patternProperties": { "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } }, "PrismQueryRow": { "type": "object", "description": "Row returned by the query endpoint. `id` is always present at the top level. Selected property values are returned under `properties`, keyed by property slug. Reference-typed values are returned as nested `{ id, properties }` objects.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "properties": { "type": "object", "description": "Selected property values keyed by property slug. For select/multiselect properties, option slugs are returned. For reference properties, values are nested `{ id, properties }` objects.", "additionalProperties": {} }, "is_user_object": { "type": "boolean" }, "source": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "LevelEnum": { "type": "string", "enum": [ "a", "r", "w" ] }, "ObjectType": { "type": "string", "description": "Object types that support CRUD, query, list, and per-type property metadata. `GET /v2/prism/{teamId}/properties` (list-all) also returns definitions for pipeline-owned types that are not in this set — including `message`, `thread`, and `linkedin_thread`. Those types are not queryable. Contacts expose `last_email` as a `ref_message`; you cannot query `message` to follow it.", "enum": [ "comment", "deal", "engagement", "identity", "ai_chat_thread", "ai_chat_message", "agent_site", "document", "action", "event", "organization", "contact" ] }, "GrantObjectType": { "type": "string", "description": "Object types whose per-record access grants can be managed. Adds `message` to the CRUD-capable `ObjectType` set: messages are owned by the Gmail sync pipeline and have no create/update/delete surface, but their access rows can still be read and written.", "enum": [ "comment", "deal", "engagement", "identity", "ai_chat_thread", "ai_chat_message", "agent_site", "document", "action", "event", "organization", "contact", "message" ] }, "PropertyType": { "type": "string", "description": "Storage type for a property definition. Determines which per-type table holds the values, and which display formats the property can take.", "enum": [ "num", "str", "bool", "date", "text", "byte", "select_str", "multi_str", "multiselect_str", "jsonb", "ref_identity", "ref_user", "ref_organization", "ref_contact", "ref_thread", "ref_message", "ref_event", "ref_account", "ref_ai_chat_thread", "ref_ai_chat_message", "multiref_ai_chat_message", "multiref_agent_site", "multiref_action", "multiref_comment", "multiref_contact", "multiref_label", "multiref_thread", "multiref_messages", "multiref_document", "multiref_identity", "multiref_organization", "multiref_engagement", "multiref_attendee", "multiref_meeting_entry", "multiref_read_receipt", "multiref_account", "multiref_source" ] }, "PropertyOption": { "type": "object", "description": "An enabled option for a select_str or multiselect_str property definition.", "required": [ "id", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "value": { "type": [ "string", "null" ], "description": "Display value for the option." }, "color_scheme": { "type": [ "string", "null" ] }, "sort_index": { "type": [ "integer", "null" ] }, "icon": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "option_group": { "type": [ "string", "null" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "crm_id": { "type": [ "string", "null" ], "format": "uuid", "deprecated": true } }, "additionalProperties": false }, "PropertyDefinition": { "type": "object", "description": "Definition for a single property on an object type. Definitions with team_id and crm_id null are shared defaults; values may be scoped to a team and/or list (crm).", "required": [ "id", "slug", "type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/PropertyType" }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "crm_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Identifier of the list this definition is scoped to, when applicable." }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Canonical identifier of the list this definition is scoped to." }, "native": { "type": "boolean" }, "locked": { "type": "boolean" }, "alias": { "type": [ "string", "null" ], "enum": [ "app_stage", null ], "description": "Reserved alias naming this definition, or null. `app_stage` marks the list pipeline stage definition. Resolve stages by this field rather than by name, slug, or team_id: a superseded native `status` definition can coexist with the pipeline one and is otherwise identical on the wire." }, "required": { "type": "boolean", "description": "When true, records of this object type must carry a non-empty value for this property on create, and a patch may not clear it." }, "role_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The property's display format. Always populated on definitions created through this API; a null here means the definition predates that and will render as an unknown format until it is patched." }, "options": { "type": "array", "description": "Present only for select_str and multiselect_str types.", "items": { "$ref": "#/components/schemas/PropertyOption" } } }, "additionalProperties": false }, "MetadataPropertiesResponse": { "type": "object", "description": "Property definitions keyed by object type, then by property definition id (UUID). When the request scopes to a single object type, only that key is present.", "additionalProperties": { "type": "object", "description": "Property definitions for one object type, keyed by property definition id (UUID).", "patternProperties": { "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": { "$ref": "#/components/schemas/PropertyDefinition" } }, "additionalProperties": false } }, "PropertyOptionCreate": { "type": "object", "description": "New option for a `select_str` or `multiselect_str` property. `type` identifies the per-type option table to write.", "required": [ "type", "value" ], "properties": { "type": { "$ref": "#/components/schemas/PropertyType" }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Scope the option to a specific list/app." }, "value": { "type": "string", "description": "Display value for the option." }, "slug": { "type": "string", "description": "URL-safe identifier. Defaults to a slugified `value`." }, "color_scheme": { "type": [ "string", "null" ] }, "sort_index": { "type": [ "integer", "null" ] }, "icon": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "option_group": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PropertyOptionPatch": { "type": "object", "description": "Partial update of a property option. `type` identifies the per-type option table to write.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/PropertyType" }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "value": { "type": "string" }, "slug": { "type": "string" }, "color_scheme": { "type": [ "string", "null" ] }, "sort_index": { "type": [ "integer", "null" ] }, "icon": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "option_group": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "PropertyDefinitionCreate": { "type": "object", "description": "New property definition. Check for an existing property first (GET the same path with `term`) and reuse it rather than defining a near-duplicate — writes address properties by slug, so two definitions sharing a slug leave no addressable winner. For `select_str`/`multiselect_str` types you may pre-seed choices via `options`.", "required": [ "type", "name" ], "properties": { "type": { "$ref": "#/components/schemas/PropertyType" }, "name": { "type": "string", "description": "Human-readable name, unique within the scope the definition is created in. A name already taken in that scope returns 409; the message names the existing definition's id, slug and type so you can write to it instead." }, "slug": { "type": "string", "description": "URL-safe identifier. When omitted it defaults to a slugified `name` and is disambiguated with a numeric suffix on conflict. When supplied explicitly it is treated as part of your write contract and is never silently renamed — a collision returns 409 instead." }, "icon": { "type": [ "string", "null" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Scopes the definition to one list/app. Omit it only for a property that genuinely belongs to the whole workspace: a definition created without `list_id` is workspace-global and surfaces on every list of this object type." }, "role_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional display format for the property, drawn from the workspace's property roles. Omit it and the canonical role for `type` is applied (plain text, plain number, checkbox). Supply it only to pick a narrower format such as email, URL or currency; the role's data type must match `type`." }, "required": { "type": "boolean", "description": "When true, records must carry a non-empty value for this property on create. Defaults to false.", "default": false }, "options": { "type": "array", "description": "Only honored when `type` is `select_str` or `multiselect_str`.", "items": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "slug": { "type": "string" }, "color_scheme": { "type": [ "string", "null" ] }, "sort_index": { "type": [ "integer", "null" ] }, "icon": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "option_group": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "PropertyDefinitionPatch": { "type": "object", "description": "Partial update of a property definition. Only `name`, `icon`, `enabled`, and `required` are editable. `type` identifies the per-type table to write.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/PropertyType" }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "required": { "type": "boolean" } }, "additionalProperties": false }, "AutomationObjectType": { "type": "string", "description": "Object types that support triggered automations. Must match the triggered-automation whitelist in @micro/database migrate-sql (TRIGGERED_AUTOMATION_OBJECTS).", "enum": [ "message", "action", "event", "document", "identity", "linkedin_message", "deal", "organization", "contact" ] }, "ViewObjectType": { "type": "string", "enum": [ "comment", "action", "deal", "engagement", "document", "event", "identity", "organization" ] }, "ViewBundle": { "type": "object", "description": "A view (saved configuration for displaying records of a given object type) plus its select/filter/sort children. Properties in select/filter/sort are referenced by slug.", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "view_type": { "type": "string" }, "combinator": { "type": "string", "enum": [ "AND", "OR" ] }, "sort_order": { "type": [ "integer", "null" ] }, "column_layout": { "type": [ "object", "null" ], "additionalProperties": true }, "group_by": { "type": [ "string", "null" ], "description": "Property slug to group by" }, "group_sort": { "type": [ "string", "null" ] }, "group_hide_empty": { "type": [ "boolean", "null" ] }, "group_hidden_option_ids": { "type": [ "array", "object", "null" ] }, "aggregation_type": { "type": [ "string", "null" ] }, "aggregation_prop_def_id": { "type": [ "string", "null" ], "format": "uuid" }, "select": { "type": "array", "description": "Property slugs (dot-paths permitted for refs)", "items": { "type": "string" } }, "filter": { "type": "array", "description": "Each entry is { slug: { comparator: value } }", "items": { "type": "object", "additionalProperties": true } }, "sort": { "type": "array", "description": "Each entry is { slug: 'asc' | 'desc' }", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "name", "view_type" ], "additionalProperties": false }, "ViewBundleWithRecords": { "type": "object", "description": "Returned by `GET /views/{viewId}?include=records`. Same `records` shape as the standalone list-view-records endpoint.", "required": [ "view", "records" ], "properties": { "view": { "$ref": "#/components/schemas/ViewBundle" }, "records": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } }, "additionalProperties": false }, "ViewBundlePatch": { "type": "object", "description": "Partial update. Any of select/filter/sort, when present, replaces that group wholesale.", "properties": { "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "view_type": { "type": "string" }, "combinator": { "type": "string", "enum": [ "AND", "OR" ] }, "sort_order": { "type": [ "integer", "null" ] }, "column_layout": { "type": [ "object", "null" ], "additionalProperties": true }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "list_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ] }, "group_by": { "type": [ "string", "null" ] }, "group_sort": { "type": [ "string", "null" ] }, "group_hide_empty": { "type": [ "boolean", "null" ] }, "group_hidden_option_ids": { "type": [ "array", "object", "null" ] }, "aggregation_type": { "type": [ "string", "null" ] }, "aggregation_prop_def_id": { "type": [ "string", "null" ], "format": "uuid" }, "select": { "type": "array", "items": { "type": "string" } }, "filter": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "sort": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": false }, "RecordOrderUpdate": { "type": "object", "properties": { "object_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "object_ids" ], "additionalProperties": false }, "ImportObjectType": { "type": "string", "enum": [ "comment", "identity", "organization", "contact", "action", "document", "engagement", "deal" ] }, "ImportRequest": { "type": "object", "required": [ "objects" ], "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/PrismObjectProperties" }, "description": "Array of objects to import with property values keyed by slug" }, "options": { "type": "object", "properties": { "dedupe_by": { "description": "Property slug to deduplicate on. A single-element array is also accepted; compound (multi-slug) dedupe is not supported yet and is rejected with guidance.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "caseInsensitive": { "type": "boolean", "default": true, "description": "Whether deduplication should be case insensitive" }, "list_id": { "type": "string", "format": "uuid", "description": "App/CRM ID for context (optional)" }, "create_missing_options": { "type": "boolean", "default": false, "description": "When true, unknown values for select/multiselect properties are created as new options instead of failing the import" }, "update_existing": { "type": "boolean", "default": false, "description": "Patch a deduplicated record with the supplied properties instead of skipping it." }, "require_list_stage": { "type": "boolean", "default": false, "description": "Require app_stage for every row in the selected list. app_stage is a reserved list-scoped alias for native status." }, "crm_id": { "type": "string", "format": "uuid", "deprecated": true, "description": "Deprecated alias for list_id." } }, "additionalProperties": false } } }, "GrantRequest": { "type": "object", "properties": { "user_id": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } } }, "team_id": { "type": "object", "minProperties": 1, "maxProperties": 1, "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "team_group_id": { "type": "array", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } } }, "share_level": { "$ref": "#/components/schemas/ShareLevel" } }, "additionalProperties": false, "anyOf": [ { "required": [ "user_id" ] }, { "required": [ "team_id" ] }, { "required": [ "team_group_id" ] } ] }, "ShareLevel": { "type": "string", "description": "How much of the record the grant exposes. `metadata` shares only the record's headers and participants; `full` shares its contents. Currently recorded on the access row and returned on read — it is not yet enforced by the read path. Applies to `message` grants; ignored for other object types.", "default": "metadata", "enum": [ "metadata", "full" ] }, "GrantResponse": { "type": "object", "description": "The grants on a record. For `message`, also carries the entity ids of everyone on the message, resolved from its address headers when the grant was written. The id arrays are read-only and are null when participant resolution was unavailable (for example the mailbox had no Gmail token at the time).", "properties": { "user_id": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "team_id": { "type": "object", "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "group_id": { "type": "object", "propertyNames": { "type": "string", "format": "uuid" }, "additionalProperties": { "$ref": "#/components/schemas/LevelEnum" } }, "share_level": { "$ref": "#/components/schemas/ShareLevel" }, "contact_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } }, "identity_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } }, "organization_ids": { "type": [ "array", "null" ], "readOnly": true, "items": { "type": "string", "format": "uuid" } } } }, "Webhook": { "type": "object", "description": "A registered webhook endpoint.", "required": [ "id", "name", "url", "team_id", "enabled", "verified", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri", "description": "Endpoint events are delivered to." }, "team_id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean", "description": "Disabled webhooks are skipped at delivery time." }, "verified": { "type": "boolean", "description": "True once the endpoint has completed the verification handshake." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_token": { "type": "string", "description": "Stable token replayed to the endpoint (as the `micro_hook_token` query param) during the verification handshake. The endpoint may check it to confirm the request originated from Micro." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookVerification": { "type": "object", "description": "Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its `verified` flag flips to true on success) to observe the outcome.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Always `pending` at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.", "enum": [ "pending" ] } } }, "WebhookWithVerification": { "description": "A webhook plus the status of a verification handshake enqueued by this request.", "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "verification": { "$ref": "#/components/schemas/WebhookVerification" } } } ] }, "WebhookWithSecret": { "description": "Returned ONLY on creation. Includes the signing secret (shown once) and the pending verification status.", "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "HMAC signing secret (prefix `whsec_`). Store it now — it is never returned again. The dispatcher signs each delivered payload with it so your endpoint can verify authenticity." }, "verification": { "$ref": "#/components/schemas/WebhookVerification" } } } ] }, "WebhookCreate": { "type": "object", "description": "On create, the dispatcher asynchronously runs a verification handshake: it sends a GET to `url` with `micro_hook_mode=subscribe`, a one-time `micro_hook_challenge`, and the webhook's `micro_hook_token`. The endpoint must respond 200 and echo the challenge value verbatim in the body; on success the webhook's `verified` flag flips to true. A failed handshake does not fail creation — re-run it later via the verify endpoint.", "required": [ "name", "url" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "format": "uri", "description": "HTTP(S) endpoint. Rejected if it resolves to a private/internal address." }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "enabled": { "type": "boolean", "default": true } } }, "WebhookUpdate": { "type": "object", "description": "Partial update. Changing `url` resets verification and re-runs the handshake.", "minProperties": 1, "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" } } }, "WebhookPingRequest": { "type": "object", "description": "Optional test event payload.", "additionalProperties": false, "properties": { "event": { "type": "string", "description": "Event name to send.", "default": "webhook.test" }, "data": { "type": "object", "description": "Arbitrary JSON payload body.", "additionalProperties": true } } }, "WebhookPingResult": { "type": "object", "required": [ "dispatched", "webhook_id", "event" ], "properties": { "dispatched": { "type": "boolean" }, "webhook_id": { "type": "string", "format": "uuid" }, "event": { "type": "string" } } }, "WebhookList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } }, "WebhookDelivery": { "type": "object", "description": "A webhook delivery — one logical event delivery to an endpoint, grouping its attempts. Status and status_code reflect the latest attempt.", "required": [ "delivery_id", "webhook_id", "type", "status", "created_at" ], "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "team_id": { "type": [ "string", "null" ], "format": "uuid" }, "type": { "type": "string", "enum": [ "delivery", "verification" ] }, "event": { "type": [ "string", "null" ], "description": "Event name (e.g. `webhook.test`); `verification` for handshake runs." }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "status_code": { "type": [ "integer", "null" ], "description": "HTTP status of the latest attempt; null on a transport error." }, "attempts": { "type": [ "integer", "null" ], "description": "Number of attempts made so far (including async retries)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookAttempt": { "type": "object", "description": "A single HTTP attempt within a delivery (including async retries).", "required": [ "attempt", "status", "created_at" ], "properties": { "attempt": { "type": "integer", "description": "1-based attempt number." }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "status_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "Failure reason, when status is failed." }, "request_body": { "type": [ "string", "null" ], "description": "Body sent to the endpoint (delivery only); may be truncated." }, "response_body": { "type": [ "string", "null" ], "description": "Body returned by the endpoint; may be truncated." }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryDetail": { "description": "A delivery plus its full attempt timeline.", "allOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "object", "properties": { "attempt_history": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } } } ] }, "WebhookDeliveryList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; null when there are no more." } } }, "RealtimeTicket": { "type": "object", "required": [ "ticket", "expires_in", "ws_url" ], "properties": { "ticket": { "type": "string", "description": "Short-lived token authenticating a realtime WebSocket connection. Pass as the `token` query parameter when connecting." }, "expires_in": { "type": "integer", "description": "Seconds until the ticket expires. Refresh (call the endpoint again) before reconnecting." }, "ws_url": { "type": [ "string", "null" ], "description": "WebSocket URL for this environment (wss://stream.developers[.staging].micro.so). Connect here with the ticket as the `token` query parameter." } } }, "PrismObjectChangeData": { "type": "object", "required": [ "objectType", "event", "teamId", "objectIds" ], "properties": { "objectType": { "$ref": "#/components/schemas/ObjectType" }, "event": { "type": "string", "enum": [ "create", "update", "delete", "restore" ], "description": "What happened to the object(s)." }, "teamId": { "type": "string", "format": "uuid" }, "objectIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Ids of the affected objects. Refetch full state via the object endpoints." }, "actorUserId": { "type": [ "string", "null" ], "description": "external_id of the user who made the change, when known. Lets a client ignore echoes of its own writes." } } }, "PrismObjectChangedEvent": { "type": "object", "required": [ "type", "data" ], "description": "Emitted on the realtime stream whenever prism objects are created, updated, deleted, or restored for a team the caller can see.", "properties": { "type": { "type": "string", "const": "prism_object_changed" }, "data": { "$ref": "#/components/schemas/PrismObjectChangeData" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key (UUID or any opaque string up to 255 chars) for an authenticated POST, PUT, or PATCH request. The server retains the initial claim for 24 hours and replays a completed non-5xx response only when the method, path, and request body all match. Reusing a non-expired key with a different method, path, or body returns 409 `idempotency_key_mismatch`; reusing it after expiry returns 409 `idempotency_key_stale`, so use a new key. Replays include the `idempotent-replay: true` response header.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency. Pass back the `etag` header from a previous GET of this record; the write only proceeds if the record hasn't changed since. Mismatch → 412 `precondition_failed`. Use `*` to require the record exists (any ETag accepted).", "schema": { "type": "string" } }, "OptionPropertyId": { "name": "propertyId", "in": "path", "required": true, "description": "Property definition uuid, or the reserved alias `app_stage` for the list pipeline stage definition (requires `list_id`). The alias exists because a superseded native `status` definition can coexist with the pipeline one and the two are indistinguishable in a metadata read; the definition carrying `alias: app_stage` is the pipeline one.", "schema": { "type": "string", "pattern": "^(app_stage|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } }, "headers": { "ETag": { "description": "Weak entity tag for the returned record. Capture and send back as `If-Match` on a subsequent PATCH or DELETE to enforce optimistic concurrency.", "schema": { "type": "string" } }, "IdempotentReplay": { "description": "Present and set to `true` when this response is a cached replay of an earlier request with the same `Idempotency-Key`. Absent on first execution.", "schema": { "type": "string", "enum": [ "true" ] } }, "Location": { "description": "URL of the resource created or whose status can be polled.", "schema": { "type": "string" } }, "XRequestId": { "description": "Correlation ID. Echoed from the request `x-request-id` header when supplied, otherwise generated. Include in support requests.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Request validation failed. Inspect `error.errors` for field-level details.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credentials. API Gateway maps a missing or invalid `x-api-key` to HTTP 401 with this envelope (including `request_id`). A 403 here means the key was accepted but the caller is not permitted.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not permitted to perform this action.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource or route does not exist.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "The HTTP method is not permitted on this resource. Returned both when the route exists but does not accept the verb, and when the underlying object cannot accept the operation (e.g., pipeline-managed objects cannot be deleted). Branch on `error.code` to distinguish.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Request conflicts with current state (e.g., duplicate or stale write).", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PreconditionFailed": { "description": "If-Match precondition failed. The resource was modified since you last read it; re-fetch and retry.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected server error. Retry with backoff; report `request_id` if persistent.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Public API key generated from Micro settings. Sent as the `x-api-key` header and validated by AWS API Gateway in front of the service." } } }, "tags": [ { "name": "Query", "description": "Filter, count, sort, and page through records." }, { "name": "Records", "description": "Create, read, update, restore, duplicate, and delete records." }, { "name": "Data model", "description": "Inspect and manage properties and select options." }, { "name": "Lists", "description": "Create and inspect workspace lists." }, { "name": "Views", "description": "Create and manage saved views and their records." }, { "name": "Sharing", "description": "Inspect and update record access." }, { "name": "Imports", "description": "Bulk-load records and inspect import jobs." }, { "name": "Automations", "description": "Create and manage triggered automations." }, { "name": "Webhooks", "description": "Manage subscriptions, verification, and delivery history." }, { "name": "Realtime", "description": "Create short-lived realtime connection tickets." } ] }