> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/api-reference/ai-and-mcp/agents.md). # Agents ## List Agent Conversations > List all agent conversations for the authenticated user. ```json {"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Agents"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: ``"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/agents/conversations":{"get":{"summary":"List Agent Conversations","description":"List all agent conversations for the authenticated user.","parameters":[{"name":"filter[title]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter conversations by title."},{"name":"filter[feature_type]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter conversations by feature type."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["messages"]},"description":"Comma-separated list of relationships to include. Available: `messages`."},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort results. Prefix with `-` for descending. Available: `id`, `title`, `created_at`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Agents"]}}}} ``` ## Start Agent Conversation > Start a new agent conversation. The agent will process the initial prompt asynchronously — poll the conversation for updated messages. ```json {"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Agents"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: ``"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/agents/conversations":{"post":{"summary":"Start Agent Conversation","description":"Start a new agent conversation. The agent will process the initial prompt asynchronously — poll the conversation for updated messages.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["feature","prompt"],"properties":{"feature":{"type":"string","description":"The feature type to use for the conversation (e.g. `script_editor`)."},"prompt":{"type":"string","maxLength":5000,"description":"The initial prompt message."},"payload":{"type":"object","nullable":true,"description":"Optional context payload passed to the agent."}}}}}},"responses":{"201":{"description":"Conversation started","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Agents"]}}}} ``` ## Get Agent Conversation > Get a single agent conversation by ID. ```json {"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Agents"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: ``"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/agents/conversations/{conversation}":{"get":{"summary":"Get Agent Conversation","description":"Get a single agent conversation by ID.","parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the conversation."},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["messages"]},"description":"Comma-separated list of relationships to include. Available: `messages`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"404":{"description":"Conversation not found"}},"tags":["Agents"]}}}} ``` ## Reply to Agent Conversation > Send a follow-up message to an existing agent conversation. The agent processes the reply asynchronously — poll the conversation for updated messages. ```json {"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Agents"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: ``"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/agents/conversations/{conversation}/reply":{"post":{"summary":"Reply to Agent Conversation","description":"Send a follow-up message to an existing agent conversation. The agent processes the reply asynchronously — poll the conversation for updated messages.","parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the conversation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":5000,"description":"The reply message."}}}}}},"responses":{"202":{"description":"Reply accepted and queued for processing"},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"404":{"description":"Conversation not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Agents"]}}}} ``` ## Get Agent Token Usage > Get the current month's agent token usage and allowance for your organisation. ```json {"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Agents"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: ``"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/agents/usage":{"get":{"summary":"Get Agent Token Usage","description":"Get the current month's agent token usage and allowance for your organisation.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Agents"]}}}} ```