spencerm
b66d72881d
Stdlib-only fs.py helper wrapping the Freshservice REST API v2 (auth, URL building, filter quoting, pagination, error surfacing), plus SKILL.md and a reference of endpoints, status/priority codes, and filter-query syntax. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
76 lines
4.1 KiB
Markdown
76 lines
4.1 KiB
Markdown
# 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:** 2 Open · 3 Pending · 4 Resolved · 5 Closed
|
||
**Ticket priority:** 1 Low · 2 Medium · 3 High · 4 Urgent
|
||
**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=...`.
|
||
|
||
Examples:
|
||
- `status:2 AND priority:3`
|
||
- `agent_id:0 AND status:2` — unassigned open tickets
|
||
- `type:'Incident' AND created_at:>'2026-06-01'`
|
||
|
||
## 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/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`.
|