Worlds / Support

Kustomer API

A local Kustomer with customers, conversations, a timeline per customer, queues, shortcuts and business rules. Test the agent that routes, merges customers and moves conversations to done.

Base path: /v1
Auth: Bearer API key, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the Kustomer world serves in the closed beta. Paths mirror the public Kustomer API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_KUSTOMER_URL`	This world's origin followed by `/v1`
`WORLDS_API_KEY`	The world key, accepted wherever Kustomer expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_KUSTOMER_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(base + "/customers?page=1&pageSize=20", { headers });
const { data } = await res.json();

API reference

13 of 13

Customers

Unified customer profiles.

GET/v1/customersList customers
POST/v1/customersCreate a customer
GET/v1/customers/{id}Get a customer
PATCH/v1/customers/{id}Update a customer

Fields · 5

`id`	string	Customer id
`type`	string	customer
`attributes.name`	string	Full name
`attributes.emails`	array	Email addresses
`attributes.phones`	array	Phone numbers

Conversations

Support threads tied to a customer.

GET/v1/conversationsList conversations
POST/v1/conversationsCreate a conversation
GET/v1/conversations/{id}Get a conversation
PATCH/v1/conversations/{id}Update a conversation

Fields · 6

`id`	string	Conversation id
`attributes.name`	string	Title
`attributes.status`	string	open or done
`attributes.priority`	integer	1 to 5
`attributes.tags`	array	Tag ids
`relationships.customer`	object	Customer link

Messages

Emails, chats and notes on a conversation.

GET/v1/conversations/{id}/messagesList messages
POST/v1/messagesCreate a message
GET/v1/messages/{id}Get a message

Fields · 5

`id`	string	Message id
`attributes.channel`	string	email, chat, sms and so on
`attributes.direction`	string	in or out
`attributes.body`	string	Message body
`attributes.subject`	string	Subject

Notes

Internal notes on a conversation.

POST/v1/conversations/{id}/notesCreate a note
GET/v1/conversations/{id}/notesList notes

Fields · 4

`id`	string	Note id
`attributes.body`	string	Note text
`attributes.createdAt`	string	ISO 8601 timestamp
`relationships.conversation`	object	Conversation link

Test workflow

Prepare. Select the Kustomer setup for your workflow and review its starting records, including customers, conversations, messages.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Dana Lee conversation in VIP queue
Dana Lee records merged by matching phone
Dana Leigh still a separate customer
No conversation done without an outbound reply
Ortiz Labs conversation still snoozed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Kustomer
version: 2
connector: kustomer
seed: kustomer-starter
mode: isolated
policy: >
  Clean up the General queue. VIP customers move to the VIP queue. Merge
  customer records only when the email or phone matches. Reply with a shortcut
  before marking anything done.
tasks:
  - id: route-a-conversation-to-the-right-queue
    prompt: Route a conversation to the right queue
  - id: merge-duplicate-customer-records
    prompt: Merge duplicate customer records
  - id: reply-with-a-shortcut-and-mark-done
    prompt: Reply with a shortcut and mark done
expected:
  - Dana Lee conversation in VIP queue
  - Dana Lee records merged by matching phone
  - Dana Leigh still a separate customer
  - No conversation done without an outbound reply
  - Ortiz Labs conversation still snoozed
scenarios:
  - rate-limited
  - merge-conflict
  - rule-overrides

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	429 on the conversations endpoint
`merge-conflict`	The customer was already merged by another agent
`rule-overrides`	A business rule reroutes the conversation after the write
`token-expired`	401 when the API key is rotated

Starting data

Start each run from the same records and relationships. The overview below describes the Kustomer starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
customers	45, five with duplicate records
conversations	50 across open, snoozed and done
queues	General, Orders, VIP
shortcuts	12 reply shortcuts
business rules	Route VIP by customer tag

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Customers records

Customers

Unified customer profiles.

Field	Type	Meaning / relationship
`id`	string	Customer id
`type`	string	customer
`attributes.name`	string	Full name
`attributes.emails`	array	Email addresses
`attributes.phones`	array	Phone numbers

json · illustrative record shape

{
  "id": "<Customer id>",
  "type": "<customer>",
  "attributes.name": "<Full name>",
  "attributes.emails": [],
  "attributes.phones": []
}

See customers operations

Conversations records

Conversations

Support threads tied to a customer.

Field	Type	Meaning / relationship
`id`	string	Conversation id
`attributes.name`	string	Title
`attributes.status`	string	open or done
`attributes.priority`	integer	1 to 5
`attributes.tags`	array	Tag ids
`relationships.customer`	object	Customer link

json · illustrative record shape

{
  "id": "<Conversation id>",
  "attributes.name": "<Title>",
  "attributes.status": "<open or done>",
  "attributes.priority": 1,
  "attributes.tags": [],
  "relationships.customer": {}
}

See conversations operations

Messages records

Messages

Emails, chats and notes on a conversation.

Field	Type	Meaning / relationship
`id`	string	Message id
`attributes.channel`	string	email, chat, sms and so on
`attributes.direction`	string	in or out
`attributes.body`	string	Message body
`attributes.subject`	string	Subject

json · illustrative record shape

{
  "id": "<Message id>",
  "attributes.channel": "<email, chat, sms and so on>",
  "attributes.direction": "<in or out>",
  "attributes.body": "<Message body>",
  "attributes.subject": "<Subject>"
}

See messages operations

Notes records

Notes

Internal notes on a conversation.

Field	Type	Meaning / relationship
`id`	string	Note id
`attributes.body`	string	Note text
`attributes.createdAt`	string	ISO 8601 timestamp
`relationships.conversation`	object	Conversation link

json · illustrative record shape

{
  "id": "<Note id>",
  "attributes.body": "<Note text>",
  "attributes.createdAt": "<ISO 8601 timestamp>",
  "relationships.conversation": {}
}

See notes operations

See the Kustomer world in the catalog