Worlds / Support

Freshdesk API

A local Freshdesk with tickets, contacts, companies, agent groups, canned responses and automation rules. Test the agent that sets priority, routes to groups and resolves tickets.

Base path: /api/v2
Auth: API key as Basic username, the world key
Endpoints: 15
Status: Active today

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

js · fetch

const base = process.env.WORLDS_FRESHDESK_URL;
const auth = "Basic " + btoa(process.env.WORLDS_API_KEY + ":X");

const res = await fetch(base + "/tickets?per_page=20", {
  headers: { Authorization: auth },
});
const tickets = await res.json();

API reference

15 of 15

Tickets

Support requests across email, portal and phone.

GET/api/v2/ticketsList tickets
POST/api/v2/ticketsCreate a ticket
GET/api/v2/tickets/{id}View a ticket
PUT/api/v2/tickets/{id}Update a ticket
GET/api/v2/search/ticketsSearch tickets

Fields · 7

`id`	integer	Ticket id
`subject`	string	Ticket subject
`status`	integer	2 open, 3 pending, 4 resolved, 5 closed
`priority`	integer	1 low to 4 urgent
`requester_id`	integer	Contact who asked
`responder_id`	integer	Agent assigned
`tags`	array	Tags

Conversations

Replies and notes on a ticket.

GET/api/v2/tickets/{id}/conversationsList conversations
POST/api/v2/tickets/{id}/replyReply to a ticket
POST/api/v2/tickets/{id}/notesAdd a note

Fields · 5

`id`	integer	Conversation id
`body_text`	string	Plain-text body
`incoming`	boolean	True if from the customer
`private`	boolean	True for a private note
`user_id`	integer	Author

Contacts

Customers who raise tickets.

GET/api/v2/contactsList contacts
POST/api/v2/contactsCreate a contact
GET/api/v2/contacts/{id}View a contact
PUT/api/v2/contacts/{id}Update a contact

Fields · 5

`id`	integer	Contact id
`name`	string	Full name
`email`	string	Email address
`company_id`	integer	Company
`active`	boolean	Whether the contact is verified

Companies

Organizations contacts belong to.

GET/api/v2/companiesList companies
POST/api/v2/companiesCreate a company
GET/api/v2/companies/{id}View a company

Fields · 4

`id`	integer	Company id
`name`	string	Company name
`domains`	array	Email domains
`health_score`	string	Account health

Test workflow

Prepare. Select the Freshdesk setup for your workflow and review its starting records, including tickets, conversations, contacts.
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 ticket in Returns group, priority Medium
Moss & Co ticket priority still Medium
Ortiz Labs ticket resolved with the Export data canned response
Dana Lee ticket still Pending
No ticket left in a group with no agent

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 · Freshdesk
version: 2
connector: freshdesk
seed: freshdesk-starter
mode: isolated
policy: >
  Sort the morning queue. Returns go to the Returns group at Medium. Billing
  fixes stay at Medium unless money is at risk. Resolve how-to questions with
  the matching canned response.
tasks:
  - id: set-priority-and-type-on-new-tickets
    prompt: Set priority and type on new tickets
  - id: route-a-ticket-to-the-right-agent-group
    prompt: Route a ticket to the right agent group
  - id: reply-with-a-canned-response-and-resolve
    prompt: Reply with a canned response and resolve
expected:
  - "Kim Park ticket in Returns group, priority Medium"
  - "Moss & Co ticket priority still Medium"
  - Ortiz Labs ticket resolved with the Export data canned response
  - Dana Lee ticket still Pending
  - No ticket left in a group with no agent
scenarios:
  - rate-limited
  - validation-failed
  - missing-field

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 once the per-minute limit is used
`validation-failed`	400 with code invalid_value on an unknown priority
`missing-field`	400 with code missing_field when a required custom field is blank
`automation-fires`	A ticket update rule reassigns the ticket after the agent's write

Starting data

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

Records	Starting setup
tickets	45 across Open, Pending, Resolved and Closed
contacts	50, linked to 10 companies
groups	Billing, Returns, Escalations
canned responses	12 in three folders
automations	Ticket creation and time trigger rules

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.

Tickets records

Tickets

Support requests across email, portal and phone.

Field	Type	Meaning / relationship
`id`	integer	Ticket id
`subject`	string	Ticket subject
`status`	integer	2 open, 3 pending, 4 resolved, 5 closed
`priority`	integer	1 low to 4 urgent
`requester_id`	integer	Contact who asked
`responder_id`	integer	Agent assigned
`tags`	array	Tags

json · illustrative record shape

{
  "id": 1,
  "subject": "<Ticket subject>",
  "status": 1,
  "priority": 1,
  "requester_id": 1,
  "responder_id": 1
}

See tickets operations

Conversations records

Conversations

Replies and notes on a ticket.

Field	Type	Meaning / relationship
`id`	integer	Conversation id
`body_text`	string	Plain-text body
`incoming`	boolean	True if from the customer
`private`	boolean	True for a private note
`user_id`	integer	Author

json · illustrative record shape

{
  "id": 1,
  "body_text": "<Plain-text body>",
  "incoming": false,
  "private": false,
  "user_id": 1
}

See conversations operations

Contacts records

Contacts

Customers who raise tickets.

Field	Type	Meaning / relationship
`id`	integer	Contact id
`name`	string	Full name
`email`	string	Email address
`company_id`	integer	Company
`active`	boolean	Whether the contact is verified

json · illustrative record shape

{
  "id": 1,
  "name": "<Full name>",
  "email": "person@example.test",
  "company_id": 1,
  "active": false
}

See contacts operations

Companies records

Companies

Organizations contacts belong to.

Field	Type	Meaning / relationship
`id`	integer	Company id
`name`	string	Company name
`domains`	array	Email domains
`health_score`	string	Account health

json · illustrative record shape

{
  "id": 1,
  "name": "<Company name>",
  "domains": [],
  "health_score": "<Account health>"
}

See companies operations

See the Freshdesk world in the catalog