Agents

List Agent Conversations

get

List all agent conversations for the authenticated user.

Authorizations

AuthorizationstringRequired

API key passed in the Authorization header. Format: <api-key>

Query parameters

filter[title]stringOptional

Filter conversations by title.

filter[feature_type]stringOptional

Filter conversations by feature type.

includestring · enumOptional

Comma-separated list of relationships to include. Available: messages.

Possible values:

sortstringOptional

Sort results. Prefix with - for descending. Available: id, title, created_at.

Responses

200

Successful response

application/json

objectOptional

401

Unauthenticated

403

Unauthorized

get/api/v1/agents/conversations

GET /api/v1/agents/conversations HTTP/1.1
Host: core.wearepatchworks.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "01hvh37yjs9kt7dd1t27azryvb",
      "feature_type": "script_editor",
      "title": "Generate order sync script",
      "payload": {
        "context": "order"
      },
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ]
}

Start Agent Conversation

post

Start a new agent conversation. The agent will process the initial prompt asynchronously — poll the conversation for updated messages.

Authorizations

AuthorizationstringRequired

API key passed in the Authorization header. Format: <api-key>

Body

featurestringRequired

The feature type to use for the conversation (e.g. script_editor).

promptstring · max: 5000Required

The initial prompt message.

payloadobject · nullableOptional

Optional context payload passed to the agent.

Responses

201

Conversation started

application/json

objectOptional

401

Unauthenticated

403

Unauthorized

422

Validation Error

application/json

post/api/v1/agents/conversations

POST /api/v1/agents/conversations HTTP/1.1
Host: core.wearepatchworks.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "feature": "script_editor",
  "prompt": "Generate a script to sync orders from Shopify to our ERP.",
  "payload": {
    "context": "order"
  }
}

{
  "data": {
    "id": "01hvh37yjs9kt7dd1t27azryvb",
    "feature_type": "script_editor",
    "title": "Generate order sync script",
    "payload": {
      "context": "order"
    },
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Get Agent Conversation

get

Get a single agent conversation by ID.

Authorizations

AuthorizationstringRequired

API key passed in the Authorization header. Format: <api-key>

Path parameters

conversationstringRequired

The unique identifier of the conversation.

Query parameters

includestring · enumOptional

Comma-separated list of relationships to include. Available: messages.

Possible values:

Responses

200

Successful response

application/json

objectOptional

401

Unauthenticated

403

Unauthorized

404

Conversation not found

get/api/v1/agents/conversations/{conversation}

GET /api/v1/agents/conversations/{conversation} HTTP/1.1
Host: core.wearepatchworks.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "01hvh37yjs9kt7dd1t27azryvb",
    "feature_type": "script_editor",
    "title": "Generate order sync script",
    "payload": {
      "context": "order"
    },
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Reply to Agent Conversation

post

Send a follow-up message to an existing agent conversation. The agent processes the reply asynchronously — poll the conversation for updated messages.

Authorizations

AuthorizationstringRequired

API key passed in the Authorization header. Format: <api-key>

Path parameters

conversationstringRequired

The unique identifier of the conversation.

Body

messagestring · max: 5000Required

The reply message.

Responses

202

Reply accepted and queued for processing

No content

401

Unauthenticated

403

Unauthorized

404

Conversation not found

422

Validation Error

application/json

post/api/v1/agents/conversations/{conversation}/reply

POST /api/v1/agents/conversations/{conversation}/reply HTTP/1.1
Host: core.wearepatchworks.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "message": "Can you also handle partial shipments?"
}

No content

Get Agent Token Usage

get

Get the current month's agent token usage and allowance for your organisation.

Authorizations

AuthorizationstringRequired

API key passed in the Authorization header. Format: <api-key>

Responses

200

Successful response

application/json

objectOptional

401

Unauthenticated

403

Unauthorized

get/api/v1/agents/usage

GET /api/v1/agents/usage HTTP/1.1
Host: core.wearepatchworks.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "tokens_used": 125000,
    "token_allowance": 500000
  }
}