REST API
Work with requests, comments, users, request types and analytics from your own scripts and tools. Calls use API keys, see one organization, and are rate limited.
- Where
- Admin → Settings → Integrations → API Keys
- Permission
- Full administrator, with a sign-in in the last 10 minutes (creating and revoking keys)
- Updated
- October 2026
Overview
Your own scripts and tools read and write requests, comments, users, request types and analytics through the REST API.
Every call needs an API key, sent as Authorization: Bearer eventier_…. An x-api-key header with the same value also works.
Each key carries scopes in the form resource:action, such as requests:read, chosen when the key is created.
Calling an endpoint outside the key's scopes returns HTTP 403, naming the missing scope.
Keys belong to one organization and only see its data.
Calls are rate limited: 120 a minute per organization, and at most 90 of those per key.
Errors return JSON with an error message and the matching HTTP status.
Every call that passes the scope and rate checks is logged against its key (method, path and status) and kept for 90 days by default.
Refused and throttled calls are recorded as security events. The key list shows when each key was last used.
Step by step
- 01
Create an API key
Create a key for the integration and give it only the scopes it needs.
- Enter a label and choose the scopes
- A reporting script needs only
analytics:read - An integration that creates tickets needs
requests:writeplusrequest-types:read - Scopes are fixed once the key is created; to change them, revoke the key and create a new one
- The key starts with
eventier_and is shown once, so store it in your secrets manager right away
- Admin → Settings → Integrations → API Keys → Generate key
- 02
Choose the key's identity
Decide who the key acts as. Use a service account for anything that runs in production.
- Personal key: acts as you, and API actions are attributed to you in the audit log
- A personal key stops working if your account is deactivated
- Service account key: belongs to a named machine identity, such as "Reporting Bot", and actions are attributed to it
- A service account can never sign in and is not billed as a seat
- Service account keys keep working when staff change
- 03
Make your first call
List the latest requests for the organization the key belongs to.
Example requestbash curl -H "Authorization: Bearer eventier_…" \ "https://<your-app-host>/api/v1/requests?limit=10" - 04
List and filter
List endpoints return one page at a time. Pass
nextCursorback ascursorto get the next page.limitsets the page size andcursorpicks the pagenextCursoris null on the last page- Requests: 25 per page by default, 100 at most
- Users and request types: 100 per page by default, 200 at most
- Requests and users accept a
qsearch; requests also acceptstatus - Invalid values return HTTP 400
Response shapejson { "requests": [...], "nextCursor": "..." } - 05
Create a request
POST to
/api/v1/requeststo create a request. The owning team comes from the request type.- Required:
requestTypeId,requesterEmailandtitle - Optional:
priorityand the type's field values - Find the
requestTypeIdwithGET /api/v1/request-types
Example requestbash curl -X POST \ -H "Authorization: Bearer eventier_…" \ -H "Content-Type: application/json" \ -d '{"requestTypeId": "<id>", "requesterEmail": "<email>", "title": "<title>"}' \ "https://<your-app-host>/api/v1/requests" - Required:
- 06
Read analytics from your own tools
Pull the same headline numbers as the Analytics dashboard into a script, spreadsheet or alert. Examples are below.
GET /api/v1/analytics/overview: volume, service level agreement (SLA) compliance and resolution percentiles- The overview also breaks the numbers down by status, team, type and priority
GET /api/v1/analytics/timeseries: a daily series for one metric,created,resolvedorsla_compliance- Both accept
fromandtodates (YYYY-MM-DD) - Both accept
teamId,requestTypeId,status,priorityandassigneeIdfilters
- 07
Stay within the rate limit
Each organization can make 120 calls a minute, shared by all its keys. Each key may use at most 90 of those.
- Creating more keys does not raise the limit; the per-key cap keeps one runaway integration from blocking the others
- Every response carries
X-RateLimit-Limit(the per-key limit),X-RateLimit-RemainingandX-RateLimit-Org-Limit - Going over either limit returns HTTP 429 with a
Retry-Afterheader - Repeated calls with a missing or invalid key are throttled per client IP
- Self-hosted installs can change both limits with the environment variables below
.env (self-hosted, defaults shown)bash # Calls per minute for the whole organization API_RATE_LIMIT_PER_MINUTE=120 # Calls per minute for any one key API_KEY_RATE_LIMIT_PER_MINUTE=90
Examples
# June's SLA compliance, straight into a spreadsheet or alert
curl -s -H "Authorization: Bearer eventier_…" \
"https://<your-app-host>/api/v1/analytics/overview?from=2026-06-01&to=2026-06-30" \
| jq .overview.slaCompliancePercent
# Daily created-ticket counts for one team (zero-filled across the range)
curl -s -H "Authorization: Bearer eventier_…" \
"https://<your-app-host>/api/v1/analytics/timeseries?metric=created&from=2026-06-01&to=2026-06-30&teamId=<id>"{
"metric": "created",
"interval": "day",
"filters": { "from": "2026-06-01", "to": "2026-06-04" },
"points": [
{ "date": "2026-06-01", "value": 0 },
{ "date": "2026-06-02", "value": 14 },
{ "date": "2026-06-03", "value": 9 },
{ "date": "2026-06-04", "value": 11 }
]
}Endpoints
Every endpoint needs an API key with the listed scope and returns data for the key's organization only. Keys created before scopes existed were given every scope.
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/requests | requests:read | List requests: supports limit (max 100), cursor, status and q |
| POST | /api/v1/requests | requests:write | Create a request (requestTypeId, requesterEmail, title; priority and field values optional) |
| GET | /api/v1/requests/{id} | requests:read | Fetch one request with comments |
| POST | /api/v1/requests/{id}/comments | requests:write | Add a comment to a request (optional authorEmail must name an active member who can edit requests, else HTTP 400) |
| GET | /api/v1/request-types | request-types:read | List request types (use the id when creating requests): supports limit (max 200) and cursor |
| GET | /api/v1/users | users:read | List users: supports limit (max 200), cursor and q |
| GET | /api/v1/analytics/overview | analytics:read | Headline metrics and SLA summary; supports from/to and team/type/status/priority/assignee filters |
| GET | /api/v1/analytics/timeseries | analytics:read | Daily series for one metric: metric=created | resolved | sla_compliance, same filters as overview |
Good to know
- Give each key only the scopes it needs. A Grafana or spreadsheet integration needs only
analytics:read, so a leaked key cannot read or write tickets. - Call logs are kept for 90 days by default. Self-hosted installs set this with
API_REQUEST_LOG_RETENTION_DAYS. - Admin → Audit logs → Security events records a key's first use, and its first use after a day idle, as
api_key.used. - Scope denials are recorded there as
api_key.scope_denied, and throttled keys asapi_key.rate_limited(once per key per minute). - Create a separate key for each integration, each under its own service account. You can then revoke one without affecting the others, and offboarding a teammate never breaks production.
- Keys created before identities existed are legacy keys that belong to the whole organization. They keep working, and their actions are attributed to an arbitrary admin.
- Replace legacy keys with keys under a service account so actions are attributed accurately.
- Confidential requests follow the key's identity. A key sees a confidential request only when its identity is a participant or grantee on that request.
- A legacy key with no identity never sees confidential requests, in request lists, request detail, comments or analytics.
- Analytics endpoints use the same data as the Analytics dashboard. Apply the same filters there to check a script's output.
- Invalid analytics filter values return HTTP 400 and name the invalid parameter. The
sla_complianceseries includes only days with at least one resolution.