Skip to content

Documentation

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

  1. 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:write plus request-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
    1. Admin → Settings → Integrations → API Keys → Generate key
  2. 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
  3. 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"
  4. 04

    List and filter

    List endpoints return one page at a time. Pass nextCursor back as cursor to get the next page.

    • limit sets the page size and cursor picks the page
    • nextCursor is 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 q search; requests also accept status
    • Invalid values return HTTP 400
    Response shapejson
    { "requests": [...], "nextCursor": "..." }
  5. 05

    Create a request

    POST to /api/v1/requests to create a request. The owning team comes from the request type.

    • Required: requestTypeId, requesterEmail and title
    • Optional: priority and the type's field values
    • Find the requestTypeId with GET /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"
  6. 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, resolved or sla_compliance
    • Both accept from and to dates (YYYY-MM-DD)
    • Both accept teamId, requestTypeId, status, priority and assigneeId filters
  7. 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-Remaining and X-RateLimit-Org-Limit
    • Going over either limit returns HTTP 429 with a Retry-After header
    • 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

Analytics from a scriptbash
# 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>"
Timeseries responsejson
{
  "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.

MethodEndpointScopePurpose
GET/api/v1/requestsrequests:readList requests: supports limit (max 100), cursor, status and q
POST/api/v1/requestsrequests:writeCreate a request (requestTypeId, requesterEmail, title; priority and field values optional)
GET/api/v1/requests/{id}requests:readFetch one request with comments
POST/api/v1/requests/{id}/commentsrequests:writeAdd a comment to a request (optional authorEmail must name an active member who can edit requests, else HTTP 400)
GET/api/v1/request-typesrequest-types:readList request types (use the id when creating requests): supports limit (max 200) and cursor
GET/api/v1/usersusers:readList users: supports limit (max 200), cursor and q
GET/api/v1/analytics/overviewanalytics:readHeadline metrics and SLA summary; supports from/to and team/type/status/priority/assignee filters
GET/api/v1/analytics/timeseriesanalytics:readDaily 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 as api_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_compliance series includes only days with at least one resolution.