Worlds / Support

Front API

A local Front with shared inboxes, conversations, tags, assignees, comments and rules. Test the agent that triages a team inbox, drafts replies and archives what is done.

Base path: /
Auth: Bearer API token, the world key
Endpoints: 14
Status: Active today

This reference previews the surface the Front world serves in the closed beta. Paths mirror the public Front 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_FRONT_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever Front expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

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

const res = await fetch(base + "/conversations?limit=25", { headers });
const { _results } = await res.json();

API reference

14 of 14

Conversations

Threads across email, chat and SMS.

GET/conversationsList conversations
GET/conversations/{conversation_id}Get a conversation
PATCH/conversations/{conversation_id}Update a conversation
PUT/conversations/{conversation_id}/assigneeAssign a conversation
GET/conversations/search/{query}Search conversations

Fields · 6

`id`	string	Conversation id
`subject`	string	Subject
`status`	string	unassigned, assigned, archived, deleted or snoozed
`assignee`	object	Assigned teammate
`recipient`	object	Customer handle
`tags`	array	Tags

Messages

Individual emails and replies.

GET/conversations/{conversation_id}/messagesList messages
POST/conversations/{conversation_id}/messagesSend a reply
GET/messages/{message_id}Get a message

Fields · 5

`id`	string	Message id
`type`	string	email, sms, custom and so on
`is_inbound`	boolean	Received from the customer
`body`	string	Message body
`author`	object	Teammate who sent it

Comments

Internal teammate discussion on a conversation.

GET/conversations/{conversation_id}/commentsList comments
POST/conversations/{conversation_id}/commentsAdd a comment

Fields · 4

`id`	string	Comment id
`body`	string	Comment text
`author`	object	Teammate
`posted_at`	number	Unix time

Contacts

Customers and their handles.

GET/contactsList contacts
POST/contactsCreate a contact
GET/contacts/{contact_id}Get a contact
PATCH/contacts/{contact_id}Update a contact

Fields · 4

`id`	string	Contact id
`name`	string	Name
`handles`	array	Email, phone and other handles
`description`	string	Notes

Test workflow

Prepare. Select the Front setup for your workflow and review its starting records, including conversations, messages, comments.
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

Kim Park conversation has a draft, no outbound message
Kim Park conversation still open with a comment for Maya
Moss & Co tagged invoice and archived
No conversation assigned to the out of office teammate
Partner digest untouched

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 · Front
version: 2
connector: front
seed: front-starter
mode: isolated
policy: >
  Triage billing@. Refund questions get a draft reply and a comment for Maya,
  never a sent message. Payment confirmations get the invoice tag and are
  archived. Leave newsletters alone.
tasks:
  - id: assign-new-conversations-to-the-right-teammate
    prompt: Assign new conversations to the right teammate
  - id: draft-a-reply-for-review-and-leave-a-comment
    prompt: Draft a reply for review and leave a comment
  - id: tag-and-archive-conversations-that-need-no-answer
    prompt: Tag and archive conversations that need no answer
expected:
  - "Kim Park conversation has a draft, no outbound message"
  - Kim Park conversation still open with a comment for Maya
  - "Moss & Co tagged invoice and archived"
  - No conversation assigned to the out of office teammate
  - Partner digest untouched
scenarios:
  - rate-limited
  - teammate-unavailable
  - conversation-moved

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 with Retry-After on the messages endpoint
`teammate-unavailable`	Assignment to an out of office teammate is rejected by a rule
`conversation-moved`	The conversation was moved to another inbox before the write
`token-revoked`	401 when the API token is rotated mid run

Starting data

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

Records	Starting setup
inboxes	support@, billing@, partners@
conversations	30 unassigned, assigned and archived
teammates	6, one out of office
tags	urgent, invoice, partner, no-reply-needed
rules	Round robin on support@

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.

Conversations records

Conversations

Threads across email, chat and SMS.

Field	Type	Meaning / relationship
`id`	string	Conversation id
`subject`	string	Subject
`status`	string	unassigned, assigned, archived, deleted or snoozed
`assignee`	object	Assigned teammate
`recipient`	object	Customer handle
`tags`	array	Tags

json · illustrative record shape

{
  "id": "<Conversation id>",
  "subject": "<Subject>",
  "status": "<unassigned, assigned, archived, deleted or snoozed>",
  "assignee": {},
  "recipient": {},
  "tags": []
}

See conversations operations

Messages records

Messages

Individual emails and replies.

Field	Type	Meaning / relationship
`id`	string	Message id
`type`	string	email, sms, custom and so on
`is_inbound`	boolean	Received from the customer
`body`	string	Message body
`author`	object	Teammate who sent it

json · illustrative record shape

{
  "id": "<Message id>",
  "type": "<email, sms, custom and so on>",
  "is_inbound": false,
  "body": "<Message body>",
  "author": {}
}

See messages operations

Comments records

Comments

Internal teammate discussion on a conversation.

Field	Type	Meaning / relationship
`id`	string	Comment id
`body`	string	Comment text
`author`	object	Teammate
`posted_at`	number	Unix time

json · illustrative record shape

{
  "id": "<Comment id>",
  "body": "<Comment text>",
  "author": {},
  "posted_at": 1
}

See comments operations

Contacts records

Contacts

Customers and their handles.

Field	Type	Meaning / relationship
`id`	string	Contact id
`name`	string	Name
`handles`	array	Email, phone and other handles
`description`	string	Notes

json · illustrative record shape

{
  "id": "<Contact id>",
  "name": "<Name>",
  "handles": [],
  "description": "<Notes>"
}

See contacts operations

See the Front world in the catalog