A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The HappyFox API is how an app or AI agent works with a helpdesk: listing and reading tickets, replying to a customer or adding a private note, moving a ticket or changing its status and assignee, and looking up contacts and staff. Access is granted through an API key paired with an auth code, which act together as the credential, and a call reaches whatever the staff member behind that key can reach, since the API has no per-method permissions of its own. The helpdesk can also push a ticket to a webhook when it is created or updated.
How an app or AI agent connects to HappyFox decides what it can reach. There is one route, a request signed with an API key and its auth code, and that pair carries the access of the staff member it belongs to.
The REST API answers under the account's own subdomain at /api/1.1/json/, for example https://acme.happyfox.com/api/1.1/json/. EU-hosted accounts use the happyfox.net domain instead. Requests and responses are JSON, and writes also accept form-encoded and multipart form data.
A webhook posts the ticket as JSON to a chosen URL when a ticket is created or updated, or when a smart rule fires. It is configured in the admin pages under Apps, Goodies, Webhooks, not through the API, and HappyFox signs each payload with HMAC-SHA1 in the X-Happyfox-Webhook-Signature header.
Every call is signed with an API key and its auth code, sent together as the username and password of HTTP Basic authentication. The pair is created in the admin pages and carries the access of the staff member it belongs to, so it reaches whatever that staff member can reach. There are no per-endpoint scopes to narrow it.
The HappyFox API is split into areas an agent can act on, such as tickets, the replies and notes on them, contacts, and the directory of staff, categories, and statuses. Each area has its own methods, and writes here change real helpdesk data that customers and agents see.
List and search tickets, read a single ticket, create one or many, and move, forward, or delete a ticket.
Add a staff reply that changes ticket properties, add a private note, post a reply as the contact, update tags, and update custom field values.
List and search contacts, read one by ID or email, create or edit a contact, and read or manage contact groups.
Read the staff list, the ticket categories, the statuses, and the ticket and contact custom field definitions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TicketsList and search tickets, read a single ticket, create one or many, and move, forward, or delete a ticket.7 | ||||||
| GET | /api/1.1/json/tickets/ | List tickets, with paging through the size and page parameters and filtering by status, category, or a search query. | read | — | Current | |
The API key has no per-method permission. A call returns whatever the staff member behind the key can see, so a key tied to a limited agent lists only that agent's visible categories. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/ticket/ | Get a single ticket's full details by its ticket number. | read | — | Current | |
Returns the ticket only if the staff member behind the key can access its category. Attachment URLs in the response expire 5 minutes after the call. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/tickets/ | Create a ticket, or up to 100 tickets in one batch by sending a list of ticket payloads. | write | — | Current | |
Tickets can be created in public categories and in categories the contact can see. Attachments are sent as multipart form data, up to 25 MB per request. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-createdRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Move a ticket to a different category. | write | — | Current | |
No per-method permission applies; the call succeeds if the key's staff member can act on the ticket. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Forward a ticket to an external email address. | write | — | Current | |
Sends the ticket contents outside the helpdesk to the address given. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Delete a ticket. | write | — | Current | |
Removes the ticket. No per-method permission applies; the call succeeds if the key's staff member is allowed to delete tickets in that category. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Subscribe a staff member to a ticket so they are notified of updates. | write | — | Current | |
No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
Replies & updatesAdd a staff reply that changes ticket properties, add a private note, post a reply as the contact, update tags, and update custom field values.5 | ||||||
| POST | /api/1.1/json/ticket/ | Add a staff reply and change ticket properties in the same call, including status, priority, and assignee. | write | — | Current | |
There is no separate endpoint for changing status or assignee; both are set through fields on this call, such as status and assignee. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Add a private staff note that the contact cannot see. | write | — | Current | |
The note is internal to staff. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Post a reply on a ticket as the contact rather than as staff. | write | — | Current | |
The reply is attributed to the contact whose user ID is sent. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Add or remove tags on a ticket. | write | — | Current | |
No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/ticket/ | Update the custom field values on a ticket. | write | — | Current | |
Field IDs come from the ticket custom fields method. No per-method permission applies; access follows the key's staff member. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook event ticket-updatedRate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
Contacts & groupsList and search contacts, read one by ID or email, create or edit a contact, and read or manage contact groups.7 | ||||||
| GET | /api/1.1/json/users/ | List contacts, with paging through the size and page parameters, or search with a query. | read | — | Current | |
Contacts are called users in the API path. Returns names, emails, and phone numbers. No per-method permission applies; access follows the key's staff member. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/user/ | Get a single contact by ID, or by email address in place of the ID. | read | — | Current | |
Returns the contact's email, phone numbers, and custom fields. No per-method permission applies; access follows the key's staff member. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/users/ | Create a new contact, or edit an existing one, with name, email, phone numbers, and custom fields. | write | — | Current | |
The same path posts a new contact or updates a matched one. No per-method permission applies; access follows the key's staff member. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/user/ | Update a specific contact by ID, including enabling or disabling their login. | write | — | Current | |
Login is toggled with the is_login_enabled field. No per-method permission applies; access follows the key's staff member. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/contact_groups/ | List all contact groups. | read | — | Current | |
No per-method permission applies; access follows the key's staff member. Acts oncontact group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/contact_groups/ | Create a contact group with a name, description, and domains. | write | — | Current | |
No per-method permission applies; access follows the key's staff member. Acts oncontact group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
| POST | /api/1.1/json/contact_group/ | Add or edit the contacts in a contact group, up to 100 per request. | write | — | Current | |
No per-method permission applies; access follows the key's staff member. Acts oncontact group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 300 POST requests per minute cap. SourceOfficial documentation ↗ | ||||||
Staff & settingsRead the staff list, the ticket categories, the statuses, and the ticket and contact custom field definitions.5 | ||||||
| GET | /api/1.1/json/staff/ | List the staff members in the account, with their roles and permissions. | read | — | Current | |
Used to resolve the staff and assignee IDs that ticket calls reference. No per-method permission applies; access follows the key's staff member. Acts onstaff Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/categories/ | List the ticket categories configured in the account. | read | — | Current | |
Used to resolve the category IDs that ticket create and move calls reference. No per-method permission applies; access follows the key's staff member. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/statuses/ | List the ticket statuses configured in the account. | read | — | Current | |
Used to resolve the status IDs that the staff update call references. No per-method permission applies; access follows the key's staff member. Acts onstatus Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/ticket_custom_fields/ | List the ticket custom field definitions and their IDs. | read | — | Current | |
Field IDs from here are needed to update a ticket's custom fields. No per-method permission applies; access follows the key's staff member. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
| GET | /api/1.1/json/user_custom_fields/ | List the contact custom field definitions and their IDs. | read | — | Current | |
Contact custom fields are called user custom fields in the API path. No per-method permission applies; access follows the key's staff member. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against the 500 GET requests per minute cap. SourceOfficial documentation ↗ | ||||||
HappyFox can notify an app or AI agent when a ticket is created or updated, instead of the app repeatedly asking. The webhook is set up in the admin pages, not through the API, and it posts the ticket as JSON to a chosen URL.
| Event | What it signals | Triggered by |
|---|---|---|
Ticket created | Fires when a ticket is created in HappyFox, posting the ticket as JSON with an event type marking it a creation. | /api/1.1/json/tickets/ |
Ticket updated | Fires when a ticket is edited in HappyFox, posting the ticket as JSON with an event type marking it an update. A smart rule firing on a ticket can also trigger this. | /api/1.1/json/ticket//api/1.1/json/ticket//api/1.1/json/ticket//api/1.1/json/ticket//api/1.1/json/ticket//api/1.1/json/ticket/ |
HappyFox limits how fast an app or AI agent can call, through a per-minute cap on requests that counts reads and writes separately. Going over returns an error and holds for a fixed window before calls are accepted again.
HappyFox applies a global per-minute cap, counting reads and writes separately: 500 GET requests per minute and 300 POST requests per minute. These account-wide limits take precedence over any limit set on an individual API key. Going over returns HTTP 429, and the API keeps returning 429 for the next 10 minutes before accepting calls again.
List endpoints such as tickets and contacts page through the size and page parameters. The default page size is 10 and the maximum is 50, so larger result sets are walked one page at a time by increasing page.
Requests and responses are JSON. A single request can carry up to 25 MB of attachments, a batch can create up to 100 tickets at once, and a contact group update can change up to 100 contacts at once. Attachment URLs in a ticket response expire 5 minutes after the call.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | Success | The call succeeded. Read calls return the requested data, and write calls return the created or updated record. | Read the JSON body for the result. |
| 400 | Bad Request | Validation failed, such as a missing required field or an invalid custom field value. The body explains which field was rejected. | Read the body, correct the named field, and resend. |
| 429 | Too Many Requests | The per-minute request cap was exceeded. HappyFox returns 429 and keeps returning it for the next 10 minutes. | Stop calling and wait out the 10 minute window before retrying, then stay under the per-minute caps. |
HappyFox serves a single API version, 1.1, addressed under the account's own subdomain. There is no dated version header to pin, so the current behaviour is whatever the live API returns.
HappyFox serves a single API version, 1.1, under each account's own subdomain at /api/1.1/json/. It accepts JSON, form-encoded, and multipart form data, and there is no dated version header to pin or migrate. HappyFox does not publish a per-version API changelog, so the live 1.1 paths are the current contract.
An integration calls the 1.1 paths directly; there is no version header to set or migrate.
HappyFox release notes ↗Bollard AI sits between a team's AI agents and HappyFox. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.