{ "openapi": "3.0.3", "info": { "title": "Duckie API", "version": "1.0.0", "description": "Read-only API for exporting Duckie runs, tool catalog data, agents, guidelines, guardrails, and runbooks." }, "servers": [ { "url": "https://app.useduckie.ai", "description": "Duckie app" } ], "security": [ { "DuckieApiKey": [] } ], "tags": [ { "name": "Runs", "description": "Run history, run detail, and run filter helpers." }, { "name": "Tools", "description": "Built-in, app, custom, and MCP tools available to the organization." }, { "name": "Agents", "description": "Agent configuration data." }, { "name": "Guidelines", "description": "Published guidelines." }, { "name": "Guardrails", "description": "Escalation and restriction guardrails." }, { "name": "Runbooks", "description": "Published, non-deleted runbooks." } ], "paths": { "/api/v1/runs": { "get": { "tags": ["Runs"], "summary": "List runs", "description": "Returns a cursor-paginated list of run summaries. The list response does not include conversation messages or execution steps.", "operationId": "listRuns", "parameters": [ { "$ref": "#/components/parameters/RunsLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "created_after", "in": "query", "description": "Return runs created at or after this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Return runs created before this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Filter by one or more run statuses. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunStatus" }, "maxItems": 200 } }, { "name": "ticket_id", "in": "query", "description": "Filter by exact source ticket or conversation ID. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200 } }, { "name": "agent_id", "in": "query", "description": "Filter by agent UUID. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200 } }, { "name": "source", "in": "query", "description": "Filter by exact run source. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 200 } }, { "name": "resolution_type", "in": "query", "description": "Filter by one or more resolution types. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResolutionType" }, "maxItems": 200 } }, { "name": "duration[eq]", "in": "query", "description": "Filter by exact run duration in seconds.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "duration[gt]", "in": "query", "description": "Filter for runs longer than this duration in seconds.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "duration[gte]", "in": "query", "description": "Filter for runs at least this many seconds long.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "duration[lt]", "in": "query", "description": "Filter for runs shorter than this duration in seconds.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "duration[lte]", "in": "query", "description": "Filter for runs no longer than this duration in seconds.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "tool_name", "in": "query", "description": "Filter by exact recorded tool name from tool-call steps. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 200 } }, { "name": "search", "in": "query", "description": "Search ticket title, ticket ID, and agent name.", "schema": { "type": "string", "maxLength": 300 } }, { "name": "metadata.", "in": "query", "description": "Filter by metadata key/value. Replace `` with a metadata key containing only letters, numbers, dots, underscores, dashes, or colons.", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "Run summaries.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/runs/{run_id}": { "get": { "tags": ["Runs"], "summary": "Retrieve a run", "description": "Returns one run with conversation messages, execution steps, evaluation attributes, and redacted tool payloads.", "operationId": "getRun", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "description": "Run detail.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/runs/tool-options": { "get": { "tags": ["Runs"], "summary": "List run tool filter options", "description": "Returns historical tool-call names that can be used with the `tool_name` run filter.", "operationId": "listRunToolOptions", "responses": { "200": { "description": "Tool filter options.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunToolOptionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/tools": { "get": { "tags": ["Tools"], "summary": "List tools", "description": "Returns the organization's tool catalog, including Duckie tools, app tools, custom tools, and MCP tools.", "operationId": "listTools", "parameters": [ { "$ref": "#/components/parameters/ConfigLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "description": "Filter by one or more tool types. Repeat the parameter for OR matching.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolType" } } }, { "name": "search", "in": "query", "description": "Search tool name, description, app integration name, and MCP server name.", "schema": { "type": "string" } }, { "name": "is_write_action", "in": "query", "description": "Filter tools by whether they perform write actions.", "schema": { "type": "boolean" } }, { "name": "requires_approval", "in": "query", "description": "Filter tools by whether they require approval.", "schema": { "type": "boolean" } }, { "name": "integration_id", "in": "query", "description": "Filter app tools by integration ID.", "schema": { "type": "string" } }, { "name": "mcp_server_id", "in": "query", "description": "Filter MCP tools by server UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tools.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/tools/{tool_id}": { "get": { "tags": ["Tools"], "summary": "Retrieve a tool", "operationId": "getTool", "parameters": [ { "$ref": "#/components/parameters/ToolId" } ], "responses": { "200": { "description": "Tool.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/agents": { "get": { "tags": ["Agents"], "summary": "List agents", "operationId": "listAgents", "parameters": [ { "$ref": "#/components/parameters/ConfigLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Agents.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/agents/{agent_id}": { "get": { "tags": ["Agents"], "summary": "Retrieve an agent", "operationId": "getAgent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Agent.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/guidelines": { "get": { "tags": ["Guidelines"], "summary": "List guidelines", "description": "Returns published guidelines.", "operationId": "listGuidelines", "parameters": [ { "$ref": "#/components/parameters/ConfigLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Guidelines.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuidelineListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/guidelines/{guideline_id}": { "get": { "tags": ["Guidelines"], "summary": "Retrieve a guideline", "operationId": "getGuideline", "parameters": [ { "$ref": "#/components/parameters/GuidelineId" } ], "responses": { "200": { "description": "Guideline.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuidelineResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/guardrails": { "get": { "tags": ["Guardrails"], "summary": "List guardrails", "operationId": "listGuardrails", "parameters": [ { "$ref": "#/components/parameters/ConfigLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "description": "Filter by guardrail type.", "schema": { "$ref": "#/components/schemas/GuardrailType" } } ], "responses": { "200": { "description": "Guardrails.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/guardrails/{guardrail_id}": { "get": { "tags": ["Guardrails"], "summary": "Retrieve a guardrail", "operationId": "getGuardrail", "parameters": [ { "$ref": "#/components/parameters/GuardrailId" } ], "responses": { "200": { "description": "Guardrail.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/runbooks": { "get": { "tags": ["Runbooks"], "summary": "List runbooks", "description": "Returns published, non-deleted runbooks.", "operationId": "listRunbooks", "parameters": [ { "$ref": "#/components/parameters/ConfigLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Runbooks.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunbookListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/runbooks/{runbook_id}": { "get": { "tags": ["Runbooks"], "summary": "Retrieve a runbook", "operationId": "getRunbook", "parameters": [ { "$ref": "#/components/parameters/RunbookId" } ], "responses": { "200": { "description": "Runbook.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunbookResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "DuckieApiKey": { "type": "http", "scheme": "bearer", "description": "API key created in Duckie Settings -> API Access." } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimit": { "description": "Request limit for the active rate-limit bucket.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests remaining in the active rate-limit bucket.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix timestamp when the active rate-limit bucket resets.", "schema": { "type": "integer" } } }, "parameters": { "RunsLimit": { "name": "limit", "in": "query", "description": "Maximum number of runs to return. Defaults to 50 and is capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ConfigLimit": { "name": "limit", "in": "query", "description": "Maximum number of records to return. Defaults to 100 and is capped at 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, "Cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page's `pagination.next_cursor` value.", "schema": { "type": "string" } }, "RunId": { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "ToolId": { "name": "tool_id", "in": "path", "required": true, "description": "Public tool ID. Duckie and app tools use `duckie:` or `app:`; custom and MCP tools use `custom:` or `mcp:`.", "schema": { "type": "string" } }, "AgentId": { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "GuidelineId": { "name": "guideline_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "GuardrailId": { "name": "guardrail_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "RunbookId": { "name": "runbook_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "The request was invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "The request is missing a valid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The API key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The resource was not found in the API key's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "A rate limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "The API could not complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "Error": { "type": "object", "required": ["code", "message", "request_id"], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthenticated", "permission_denied", "not_found", "rate_limited", "internal_error" ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "retry_after": { "type": "integer", "minimum": 1 } } }, "Pagination": { "type": "object", "required": ["limit", "next_cursor", "has_more"], "properties": { "limit": { "type": "integer" }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } }, "RunStatus": { "type": "string", "enum": ["completed", "running", "failed", "cancelled", "paused"] }, "ResolutionType": { "type": "string", "enum": ["deflected", "resolved", "escalated", "pending"] }, "ToolType": { "type": "string", "enum": ["duckie_tool", "app_tool", "custom_tool", "mcp_tool"] }, "GuardrailType": { "type": "string", "enum": ["escalation", "restriction"] }, "RunListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "RunDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/RunDetail" } } }, "RunToolOptionsResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunToolOption" } } } }, "RunSummary": { "type": "object", "required": [ "id", "object", "created_at", "updated_at", "status", "source", "duration_seconds", "ticket", "agent", "category", "resolution", "trigger", "approval", "scheduled_resume_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": ["run"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "nullable": true }, "source": { "type": "string" }, "duration_seconds": { "type": "number" }, "ticket": { "$ref": "#/components/schemas/RunTicket" }, "agent": { "$ref": "#/components/schemas/NullableEntityRef" }, "category": { "$ref": "#/components/schemas/NullableEntityRef" }, "resolution": { "$ref": "#/components/schemas/NullableResolution" }, "trigger": { "$ref": "#/components/schemas/RunTriggerSummary" }, "approval": { "$ref": "#/components/schemas/RunApproval" }, "scheduled_resume_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RunDetail": { "allOf": [ { "$ref": "#/components/schemas/RunSummary" }, { "type": "object", "required": ["conversation", "steps", "evaluation_attributes"], "properties": { "trigger": { "$ref": "#/components/schemas/RunTriggerDetail" }, "agent": { "$ref": "#/components/schemas/RunAgentDetail" }, "conversation": { "type": "array", "items": { "$ref": "#/components/schemas/RunMessage" } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RunStep" } }, "evaluation_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/RunEvaluationAttribute" } } } } ] }, "RunTicket": { "type": "object", "required": ["id", "title", "url"], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "nullable": true } } }, "NullableEntityRef": { "type": "object", "nullable": true, "required": ["id", "name"], "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "RunAgentDetail": { "type": "object", "required": ["id", "name", "description"], "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } } }, "NullableResolution": { "type": "object", "nullable": true, "required": ["type", "summary"], "properties": { "type": { "type": "string" }, "summary": { "type": "string" } } }, "RunTriggerSummary": { "type": "object", "properties": { "event_type": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "nullable": true }, "ticket_status": { "type": "string", "nullable": true }, "ticket_priority": { "type": "string", "nullable": true }, "ticket_tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "trigger_message_type": { "type": "string", "nullable": true }, "internal_notes_only": { "type": "boolean", "nullable": true }, "is_messaging_ticket": { "type": "boolean", "nullable": true }, "customer_name": { "type": "string", "nullable": true } } }, "RunTriggerDetail": { "allOf": [ { "$ref": "#/components/schemas/RunTriggerSummary" }, { "type": "object", "properties": { "message_text": { "type": "string", "nullable": true }, "latest_comment": { "type": "string", "nullable": true } } } ] }, "RunApproval": { "type": "object", "required": ["waiting_for_approval", "pending"], "properties": { "waiting_for_approval": { "type": "boolean" }, "pending": { "$ref": "#/components/schemas/NullablePendingApproval" } } }, "NullablePendingApproval": { "type": "object", "nullable": true, "properties": { "step_id": { "type": "string", "nullable": true }, "tool_id": { "type": "string", "nullable": true }, "tool_name": { "type": "string", "nullable": true }, "tool_type": { "type": "string", "nullable": true }, "params": { "description": "Redacted and truncated approval parameters.", "nullable": true }, "redacted": { "type": "boolean" }, "truncated": { "type": "boolean" } } }, "RunMessage": { "type": "object", "required": [ "id", "order", "role", "user_name", "message", "source_timestamp", "recorded_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order": { "type": "integer" }, "role": { "type": "string", "nullable": true }, "user_name": { "type": "string", "nullable": true }, "message": { "type": "string" }, "source_timestamp": { "type": "string", "nullable": true }, "recorded_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RunStep": { "type": "object", "required": [ "id", "order", "timestamp", "type", "title", "content", "status", "duration_seconds" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "nullable": true }, "title": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "nullable": true }, "duration_seconds": { "type": "number", "nullable": true }, "tool": { "$ref": "#/components/schemas/RunStepTool" } } }, "RunStepTool": { "type": "object", "description": "Present when a step is a tool call or has a recorded tool name.", "required": ["name", "type", "input", "output", "redacted", "truncated", "error"], "properties": { "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "input": { "description": "Redacted and truncated tool input payload.", "nullable": true }, "output": { "description": "Redacted and truncated tool output payload.", "nullable": true }, "redacted": { "type": "boolean" }, "truncated": { "type": "boolean" }, "error": { "type": "string", "nullable": true } } }, "RunEvaluationAttribute": { "type": "object", "required": ["id", "attribute_id", "name", "description", "value", "recorded_at"], "properties": { "id": { "type": "string", "format": "uuid" }, "attribute_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true }, "recorded_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RunToolOption": { "type": "object", "required": ["tool_name", "display_name", "run_count"], "properties": { "tool_name": { "type": "string" }, "display_name": { "type": "string" }, "run_count": { "type": "integer" } } }, "ToolListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ToolResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Tool" } } }, "Tool": { "type": "object", "required": [ "id", "object", "type", "name", "description", "is_write_action", "requires_approval", "enabled", "parameters", "duckie", "app", "custom", "mcp", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": ["tool"] }, "type": { "$ref": "#/components/schemas/ToolType" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_write_action": { "type": "boolean" }, "requires_approval": { "type": "boolean" }, "enabled": { "type": "boolean" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ToolParameter" } }, "duckie": { "$ref": "#/components/schemas/NullableDuckieToolMetadata" }, "app": { "$ref": "#/components/schemas/NullableAppToolMetadata" }, "custom": { "$ref": "#/components/schemas/NullableCustomToolMetadata" }, "mcp": { "$ref": "#/components/schemas/NullableMcpToolMetadata" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ToolParameter": { "type": "object", "required": ["name", "type", "required", "description", "has_preset_value"], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "has_preset_value": { "type": "boolean", "description": "True when the tool parameter has a preset value. The value itself is not exposed." } } }, "NullableDuckieToolMetadata": { "type": "object", "nullable": true, "properties": { "category": { "type": "string", "nullable": true }, "availability": { "type": "string", "nullable": true } } }, "NullableAppToolMetadata": { "type": "object", "nullable": true, "properties": { "integration_id": { "type": "string" }, "integration_name": { "type": "string" }, "connection_mode": { "type": "string", "enum": ["customer", "system"] }, "connection_status": { "type": "string" } } }, "NullableCustomToolMetadata": { "type": "object", "nullable": true, "properties": { "endpoint": { "type": "string" }, "method": { "type": "string" }, "body_format": { "type": "string" }, "headers": { "type": "array", "items": { "type": "object", "required": ["name", "value"], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "http_timeout_sec": { "type": "integer", "nullable": true }, "auth": { "type": "object", "nullable": true, "additionalProperties": true } } }, "NullableMcpToolMetadata": { "type": "object", "nullable": true, "properties": { "server_id": { "type": "string", "format": "uuid" }, "server_name": { "type": "string", "nullable": true }, "mcp_tool_name": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true } } }, "AgentListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "AgentResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } }, "Agent": { "type": "object", "required": [ "id", "object", "name", "description", "status", "last_run_at", "start_with", "instructions", "model_config", "tool_ids", "resolution_tracking", "resolution_rule_ids", "knowledge_tags", "guideline_ids", "guardrail_ids", "attribute_ids", "category_ids", "included_runbook_ids", "excluded_runbook_ids", "included_workflow_ids", "excluded_workflow_ids", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": ["agent"] }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "start_with": { "type": "object", "required": ["type", "id", "name"], "properties": { "type": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "instructions": { "type": "string", "nullable": true }, "model_config": { "type": "object", "nullable": true, "additionalProperties": true }, "tool_ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "resolution_tracking": { "type": "boolean" }, "resolution_rule_ids": { "type": "array", "items": { "type": "string" } }, "knowledge_tags": { "type": "array", "items": { "type": "string" } }, "guideline_ids": { "type": "array", "items": { "type": "string" } }, "guardrail_ids": { "type": "array", "items": { "type": "string" } }, "attribute_ids": { "type": "array", "items": { "type": "string" } }, "category_ids": { "type": "array", "items": { "type": "string" } }, "included_runbook_ids": { "type": "array", "items": { "type": "string" } }, "excluded_runbook_ids": { "type": "array", "items": { "type": "string" } }, "included_workflow_ids": { "type": "array", "items": { "type": "string" } }, "excluded_workflow_ids": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GuidelineListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guideline" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "GuidelineResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Guideline" } } }, "Guideline": { "type": "object", "required": ["id", "object", "title", "content", "section", "created_at", "updated_at"], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": ["guideline"] }, "title": { "type": "string" }, "content": { "type": "string" }, "section": { "$ref": "#/components/schemas/NullableGuidelineSection" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "NullableGuidelineSection": { "type": "object", "nullable": true, "required": ["id", "name", "description", "icon"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" } } }, "GuardrailListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guardrail" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "GuardrailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Guardrail" } } }, "Guardrail": { "type": "object", "required": ["id", "object", "title", "content", "type", "created_at", "updated_at"], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": ["guardrail"] }, "title": { "type": "string" }, "content": { "type": "string" }, "type": { "$ref": "#/components/schemas/GuardrailType" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RunbookListResponse": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Runbook" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "RunbookResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Runbook" } } }, "Runbook": { "type": "object", "required": [ "id", "object", "name", "description", "content", "type", "used_by_agent_ids", "folder_id", "inserts", "model_config", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "enum": ["runbook"] }, "name": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "used_by_agent_ids": { "type": "array", "items": { "type": "string" } }, "folder_id": { "type": "string", "nullable": true }, "inserts": { "type": "array", "items": { "$ref": "#/components/schemas/RunbookInsert" } }, "model_config": { "type": "object", "nullable": true, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RunbookInsert": { "type": "object", "required": ["id", "name", "type", "source"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "source": { "type": "string" } } } } } }