freshservice-claude/reference.md

Freshservice API v2 reference

Base URL: https://<domain>.freshservice.com/api/v2. Auth is HTTP Basic with the API key as username (handled by scripts/fs.py). Full docs: https://api.freshservice.com

Codes

Ticket status (defaults): 2 Open · 3 Pending · 4 Resolved · 5 Closed Ticket priority: 1 Low · 2 Medium · 3 High · 4 Urgent

⚠️ Instances often define custom statuses beyond the 4 defaults (e.g. "Working", "Scheduled", "Waiting Vendor Support"). Resolved and Closed are always ids 4 and 5; every other status is "open". To list them all, read the status field choices: GET /ticket_form_fields → field where name == "status" → choices[]. So "all my tickets that aren't resolved/closed" must enumerate every non-4/5 status, not just (status:2 OR status:3). Recipe: agent_id:<id> AND (status:2 OR status:3 OR status:6 OR status:7 OR ...) using all open ids from the status field. Ticket source: 1 Email · 2 Portal · 3 Phone · 4 Chat · 5 Feedback widget · 6 Yammer · 7 AWS CloudWatch · 8 PagerDuty · 9 Walkup · 10 Slack

Status/priority for changes use their own workflow codes; list a few existing records to infer them, or read the ticket-fields / change-fields endpoints.

Endpoints

Resource	List	Create	View	Update	Delete
Tickets	GET /tickets	POST /tickets	GET /tickets/{id}	PUT /tickets/{id}	DELETE /tickets/{id}
Ticket filter	GET /tickets/filter?query="..."	—	—	—	—
Conversations	GET /tickets/{id}/conversations	reply: POST /tickets/{id}/reply; note: POST /tickets/{id}/notes	—	PUT /conversations/{id}	DELETE /conversations/{id}
Assets	GET /assets	POST /assets	GET /assets/{display_id}	PUT /assets/{display_id}	DELETE /assets/{display_id}
Agents	GET /agents	POST /agents	GET /agents/{id}	PUT /agents/{id}	—
Requesters	GET /requesters	POST /requesters	GET /requesters/{id}	PUT /requesters/{id}	—
Groups	GET /groups	POST /groups	GET /groups/{id}	PUT /groups/{id}	DELETE /groups/{id}
Departments	GET /departments	POST /departments	GET /departments/{id}	PUT /departments/{id}	DELETE /departments/{id}
Changes	GET /changes (+ /changes/filter)	POST /changes	GET /changes/{id}	PUT /changes/{id}	DELETE /changes/{id}
Problems	GET /problems	POST /problems	GET /problems/{id}	PUT /problems/{id}	DELETE /problems/{id}
Releases	GET /releases	POST /releases	GET /releases/{id}	PUT /releases/{id}	DELETE /releases/{id}
Current agent	GET /agents/me	—	—	—	—

Other useful endpoints reachable the same way: /solutions/categories, /solutions/folders, /solutions/articles, /products, /vendors, /ticket_fields, /tickets/{id}/time_entries, /canned_responses.

Ticket fields (create/update)

subject, description (HTML ok), email or requester_id, priority, status, source, group_id, responder_id (assigned agent), type (e.g. "Incident", "Service Request"), tags (array), category, sub_category, custom_fields (object), due_by, fr_due_by.

Provide either email or requester_id. For a public reply the requester is emailed; a note with "private": true is internal-only.

Filter (query) syntax — /tickets/filter and /changes/filter

• Format: field:value, combined with AND / OR.
• Strings single-quoted: tag:'vip'. Numbers/dates bare or quoted.
• Operators on dates/numbers: >, <, e.g. created_at:>'2026-01-01'.
• Filterable ticket fields include: status, priority, agent_id, group_id, requester_id, type, source, tag, created_at, updated_at, due_by, plus custom fields by name.
• The whole expression must be URL-double-quoted; scripts/fs.py does this when you pass --param query=... / --param filter=....

Two common gotchas:

• Assignee is agent_id (numeric), not an email. Resolve an email to an id first: GET /agents?email=person@co.com → read id, then filter on it.
• No "not" operator for status. "Open / unresolved / not closed" must be enumerated: (status:2 OR status:3). Parenthesize the OR group when AND-ing it.

Examples:

• status:2 AND priority:3
• agent_id:0 AND status:2 — unassigned open tickets
• agent_id:21000816864 AND (status:2 OR status:3) — assigned to an agent, still open
• type:'Incident' AND created_at:>'2026-06-01'

Multi-workspace accounts: /tickets/filter searches one workspace by default. Pass --param workspace_id=<id> to target another (an agent's workspace_ids lists which ones they're in).

Listing vs. filtering

• GET /tickets supports filter presets (new_and_my_open, watching, spam, deleted), updated_since, order_by, order_type, page, per_page (max 100), and include (conversations, requester, stats).
• GET /tickets/{id}?include=assets is the only way to see a ticket's associated CMDB assets — they come back embedded in the ticket object. There is no /tickets/{id}/associated-assets endpoint (it 404s). Other single-ticket includes: conversations, requester, requested_for, stats, problem, tags, related_tickets.
• GET /tickets/filter?query="..." is for ad-hoc field queries (also 100/page).

Pagination & rate limits

• 30 results/page default, 100 max via per_page. scripts/fs.py surfaces next_page when a next-page Link header is present.
• Per-plan minute limits (100–500/min). Responses include rate_limit_remaining.