{ "openapi": "3.1.0", "info": { "title": "Rulebase API", "version": "1.0.0", "description": "Upload conversations and work items, then read their processing and evaluation results using an organization API key." }, "servers": [ { "url": "https://api.rulebase.co", "description": "US" }, { "url": "https://eu.api.rulebase.co", "description": "EU" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Rulebase organization API key" } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/identity": { "get": { "tags": ["Identity"], "summary": "Get API key identity", "description": "Returns the organization identity authenticated by the API key.", "operationId": "getIdentity", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Authenticated organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "workos_organization_id": { "type": "string", "nullable": true }, "timezone": { "type": "string" } }, "required": [ "id", "name", "workos_organization_id", "timezone" ] } }, "required": ["organization"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/organization": { "get": { "tags": ["Organization"], "summary": "Get the current organization", "description": "Returns safe metadata for the organization authenticated by the API key.", "operationId": "getCurrentOrganization", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Authenticated organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "workos_organization_id": { "type": "string", "nullable": true }, "timezone": { "type": "string" } }, "required": [ "id", "name", "workos_organization_id", "timezone" ] } }, "required": ["organization"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/conversation_uploads/{id}": { "get": { "tags": ["Conversation uploads"], "summary": "Get a conversation upload", "description": "Retrieves a conversation upload by its Rulebase upload ID.", "operationId": "getConversationUpload", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Conversation upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "expired", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "status", "created_at", "updated_at"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Conversation upload not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/conversation_uploads/presign": { "post": { "tags": ["Conversation uploads"], "summary": "Generate a presigned URL for conversation upload", "description": "Generates a presigned URL that can be used to upload conversations. The URL expires in 30 minutes.", "operationId": "generatePresignedUrlForConversationUpload", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "filename": { "type": "string", "description": "The archive filename, including its extension." }, "source": { "type": "string", "enum": ["outreach_kaia", "xcally"] } }, "required": ["filename", "source"] } }, "required": ["upload"] } } } }, "responses": { "200": { "description": "Presigned upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": ["id", "url"] } }, "required": ["upload"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/conversation_uploads": { "post": { "tags": ["Conversation uploads"], "summary": "Upload a conversation", "description": "Uploads one conversation as multipart form data. Use this endpoint for recordings up to 100 MB.", "operationId": "uploadConversation", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "upload[source]": { "type": "string", "enum": ["outreach_kaia", "xcally"] }, "upload[metadata][unique_id]": { "type": "string" }, "upload[metadata][type]": { "type": "string", "enum": ["inbound", "outbound"] }, "upload[metadata][agent]": { "type": "string" }, "upload[metadata][caller]": { "type": "string" }, "upload[metadata][called]": { "type": "string" }, "upload[metadata][recorded_at]": { "type": "string" }, "upload[file]": { "type": "string", "format": "binary" } }, "required": [ "upload[source]", "upload[metadata][unique_id]", "upload[metadata][type]", "upload[metadata][agent]", "upload[metadata][caller]", "upload[metadata][called]", "upload[metadata][recorded_at]", "upload[file]" ] } } } }, "responses": { "201": { "description": "Conversation uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "expired", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "status", "created_at", "updated_at"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "get": { "tags": ["Conversation uploads"], "summary": "List conversation uploads", "description": "Returns conversation uploads for the organization.", "operationId": "listConversationUploads", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "source", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "external_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "updated_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "updated_before", "in": "query" } ], "responses": { "200": { "description": "Conversation uploads", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "source", "external_id", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "object", "properties": { "next": { "type": "string", "nullable": true }, "limit": { "type": "integer" } }, "required": ["next", "limit"] } }, "required": ["page"] } }, "required": ["data", "meta"] } } } }, "400": { "description": "Invalid filters or pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/evaluations": { "get": { "tags": ["Evaluations"], "summary": "List evaluations", "description": "Returns agent evaluations.", "operationId": "listEvaluations", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "source_channel", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "channel_types", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "updated_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "updated_before", "in": "query" } ], "responses": { "200": { "description": "Active agent evaluations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "required": ["id", "name", "email"] }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scorecards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scorecard": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": ["id", "name"] }, "score": { "type": "number", "nullable": true }, "max_score": { "type": "number", "nullable": true }, "criteria": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "criterion": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": ["id", "name"] }, "score": { "type": "number", "nullable": true }, "max_score": { "type": "number", "nullable": true } }, "required": [ "id", "criterion", "score", "max_score" ] } } }, "required": [ "id", "scorecard", "score", "max_score", "criteria" ] } }, "conversation": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "field_values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "field": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "key", "name"] }, "value": { "nullable": true } }, "required": ["id", "field"] } } }, "required": ["id", "external_id", "field_values"] }, "work_item": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "external_id", "type"] } }, "required": [ "id", "source", "agent", "score", "created_at", "updated_at", "scorecards", "conversation", "work_item" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "object", "properties": { "next": { "type": "string", "nullable": true }, "limit": { "type": "integer" } }, "required": ["next", "limit"] } }, "required": ["page"] } }, "required": ["data", "meta"] } } } }, "400": { "description": "Invalid filters or pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items": { "post": { "tags": ["Work items"], "summary": "Create a work item", "description": "Create a work item. Fails with 409 when the external ID already exists; use PATCH or batch apply to update.", "operationId": "createWorkItem", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "work_item": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1 }, "agent_email": { "type": "string", "format": "email" }, "agent_name": { "type": "string", "minLength": 1 }, "agent_external_id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true }, "default": {} }, "events": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1 }, "actor_email": { "type": "string", "format": "email" }, "actor_name": { "type": "string", "minLength": 1 }, "actor_external_id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" } }, "required": ["external_id"] }, "default": [] } }, "required": ["external_id"] } }, "required": ["work_item"] } } } }, "responses": { "201": { "description": "Work item created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] } }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "short_description": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "actor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "actor", "content", "occurred_at", "deleted_at", "created_at" ] } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 } }, "required": [ "id", "external_id", "agent", "agents", "type", "status", "short_description", "description", "completed_at", "custom_attributes", "events", "created_at", "updated_at", "qa_score" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "409": { "description": "A work item with this external ID already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "422": { "description": "Invalid work item", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "get": { "tags": ["Work items"], "summary": "List work items", "description": "List work items newest-completion-first. Pass the returned `meta.page.next` cursor to fetch the following page. Deleted work items are excluded.", "operationId": "listWorkItems", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "external_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "completed_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "completed_before", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "query", "in": "query" } ], "responses": { "200": { "description": "Work items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] } }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "short_description": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 } }, "required": [ "id", "external_id", "agent", "agents", "type", "status", "short_description", "description", "completed_at", "custom_attributes", "created_at", "updated_at", "qa_score" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "object", "properties": { "next": { "type": "string", "nullable": true }, "limit": { "type": "integer" } }, "required": ["next", "limit"] } }, "required": ["page"] } }, "required": ["data", "meta"] } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items/{id}": { "patch": { "tags": ["Work items"], "summary": "Update a work item", "description": "Update a work item. Omitted fields keep their stored values, `custom_attributes` are merged, and `external_id` is immutable.", "operationId": "updateWorkItem", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "work_item": { "type": "object", "properties": { "agent_email": { "type": "string", "format": "email" }, "agent_name": { "type": "string", "minLength": 1 }, "agent_external_id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } } }, "additionalProperties": false } }, "required": ["work_item"] } } } }, "responses": { "200": { "description": "Work item updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] } }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "short_description": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "actor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "actor", "content", "occurred_at", "deleted_at", "created_at" ] } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 } }, "required": [ "id", "external_id", "agent", "agents", "type", "status", "short_description", "description", "completed_at", "custom_attributes", "events", "created_at", "updated_at", "qa_score" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Work item not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "422": { "description": "Invalid work item", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "delete": { "tags": ["Work items"], "summary": "Delete a work item", "description": "Soft-delete a work item. Idempotent: deleting an already-deleted or unknown work item still returns 200 with `deleted: false`. Re-applying the same external ID restores it.", "operationId": "deleteWorkItem", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Work item deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } }, "required": ["id", "deleted"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "get": { "tags": ["Work items"], "summary": "Get a work item", "description": "Retrieve a work item by its ID.", "operationId": "getWorkItem", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Work item found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] } }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "short_description": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "actor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "actor", "content", "occurred_at", "deleted_at", "created_at" ] } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 } }, "required": [ "id", "external_id", "agent", "agents", "type", "status", "short_description", "description", "completed_at", "custom_attributes", "events", "created_at", "updated_at", "qa_score" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Work item not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items/batch": { "post": { "tags": ["Work items"], "summary": "Apply a batch of work items", "description": "Create, update, or restore up to 100 work items by external ID. Results preserve input order; a failed item does not roll back the others, and omitted work items are never deleted. Set `dry_run` to preview the outcome without writing.", "operationId": "applyWorkItems", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "work_items": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1 }, "agent_email": { "type": "string", "format": "email" }, "agent_name": { "type": "string", "minLength": 1 }, "agent_external_id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true }, "default": {} }, "events": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1 }, "actor_email": { "type": "string", "format": "email" }, "actor_name": { "type": "string", "minLength": 1 }, "actor_external_id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" } }, "required": ["external_id"] }, "default": [] } }, "required": ["external_id"] }, "minItems": 1, "maxItems": 100 }, "dry_run": { "type": "boolean", "default": false } }, "required": ["work_items"] } } } }, "responses": { "200": { "description": "Batch applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "restored": { "type": "integer" }, "error": { "type": "integer" } }, "required": [ "total", "created", "updated", "unchanged", "restored", "error" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "external_id": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "unchanged", "restored", "error" ] }, "data": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] } }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "cancelled" ] }, "short_description": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true, "format": "date-time" }, "custom_attributes": { "type": "object", "additionalProperties": { "nullable": true } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "qa_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 } }, "required": [ "id", "external_id", "agent", "agents", "type", "status", "short_description", "description", "completed_at", "custom_attributes", "created_at", "updated_at", "qa_score" ] }, "error": { "type": "string", "nullable": true } }, "required": [ "index", "external_id", "status", "data", "error" ] } } }, "required": ["dry_run", "summary", "results"] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "422": { "description": "Invalid work item", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items/upload/{id}": { "get": { "tags": ["Work items"], "summary": "Get a work item upload", "description": "Retrieve a work item upload by its ID to check processing status.", "operationId": "getWorkItemUpload", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Work item upload found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "completed_with_errors", "failed" ] }, "total_rows": { "type": "integer" }, "succeeded_rows": { "type": "integer" }, "failed_rows": { "type": "integer" }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "total_rows", "succeeded_rows", "failed_rows", "error", "created_at", "updated_at" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Work item upload not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items/upload": { "post": { "tags": ["Work items"], "summary": "Upload work items in bulk", "description": "Upload work items from a CSV file.", "operationId": "uploadWorkItems", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "upload[file]": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Work item upload accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "completed_with_errors", "failed" ] }, "total_rows": { "type": "integer" }, "succeeded_rows": { "type": "integer" }, "failed_rows": { "type": "integer" }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "total_rows", "succeeded_rows", "failed_rows", "error", "created_at", "updated_at" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "422": { "description": "Invalid upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/work_items/{id}/events": { "post": { "tags": ["Work items"], "summary": "Create or update a work item event", "description": "Create or update an event associated with a work item. Events are upserted by external ID.", "operationId": "upsertWorkItemEvent", "security": [{ "bearerAuth": [] }], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1 }, "actor_email": { "type": "string", "format": "email" }, "actor_name": { "type": "string", "minLength": 1 }, "actor_external_id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" } }, "required": ["external_id"] } }, "required": ["event"] } } } }, "responses": { "201": { "description": "Work item event created or updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "actor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "email", "external_id", "avatar_url" ] }, "content": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "nullable": true, "format": "date-time" }, "deleted_at": { "type": "string", "nullable": true, "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "actor", "content", "occurred_at", "deleted_at", "created_at" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Work item not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "422": { "description": "Invalid work item event", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/agent_releases": { "post": { "tags": ["Agent releases"], "summary": "Record an agent release", "description": "Records that a new version of an agent was deployed. Call it from CI after each production deploy. Sending the same `commit_sha` (or, without one, the same `name`) again returns the existing release, so retries are safe.", "operationId": "createAgentRelease", "security": [{ "bearerAuth": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid", "description": "The agent's ID, from Settings → Agents." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Version label shown in Agent monitoring, e.g. v1.4.2." }, "released_at": { "type": "string", "format": "date-time", "description": "When the deploy finished. Defaults to now." }, "commit_sha": { "type": "string", "minLength": 7, "maxLength": 64 }, "notes": { "type": "string", "maxLength": 2000 } }, "required": ["agent_id", "name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "A release for this commit or name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "released_at": { "type": "string", "nullable": true, "format": "date-time" }, "released_on": { "type": "string" }, "commit_sha": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "agent_id", "name", "released_at", "released_on", "commit_sha", "notes" ] } }, "required": ["data"] } } } }, "201": { "description": "Release recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "released_at": { "type": "string", "nullable": true, "format": "date-time" }, "released_on": { "type": "string" }, "commit_sha": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "agent_id", "name", "released_at", "released_on", "commit_sha", "notes" ] } }, "required": ["data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } } } }