Skip to main content
API とデータ / REST API

REST API

The endpoints and defaults below describe the Laravel adapter. Mobile customer endpoints are a separate contract; other adapters have their own routes and authentication requirements.

Escalated includes a full REST API for programmatic access to tickets, agents, departments, and more.

Headless mode -- The REST API works independently of the UI setting and is fully functional in headless deployments. It is the recommended interface for building custom frontends.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer your-api-token

Tokens are created in the admin panel under API Tokens. Each token has:

  • Name — descriptive label
  • Abilities — granular permissions (e.g. agent, admin)
  • Expiration — optional expiry date

Validate a token

POST /auth/validate

Returns the token owner's info, abilities, and role.

Base URL

All endpoints are prefixed with your configured API prefix (default: /support/api/v1).

Endpoints

Dashboard

Method Path Description
GET /dashboard Agent dashboard stats (open, assigned, unassigned, SLA breached, resolved today)

Tickets

Method Path Description
GET /tickets List tickets (paginated, filterable)
POST /tickets Create a new ticket
GET /tickets/{reference} Ticket detail with replies and activities
POST /tickets/{reference}/reply Add reply or internal note
PATCH /tickets/{reference}/status Change ticket status
PATCH /tickets/{reference}/priority Change ticket priority
POST /tickets/{reference}/assign Assign to agent
POST /tickets/{reference}/follow Toggle follow/unfollow
POST /tickets/{reference}/macro Apply a macro
POST /tickets/{reference}/tags Sync tags
DELETE /tickets/{reference} Delete ticket

Resources (read-only)

Method Path Description
GET /agents List all agents
GET /departments List active departments
GET /tags List all tags
GET /canned-responses List available canned responses
GET /macros List available macros
GET /realtime/config WebSocket/realtime configuration

Token management uses the authenticated admin interface; it is not provided by the agent API routes listed above.

Filtering & Pagination

Ticket list query parameters

Parameter Type Description
status string Filter by status (open, in_progress, resolved, etc.)
priority string Filter by priority (low, medium, high, urgent, critical)
department_id integer Filter by department
assigned_to integer Filter by assigned agent ID
unassigned boolean 1 or true for unassigned only
ticket_type string Filter by type (question, problem, incident, task)
search string Search subject, description, and reference
sla_breached boolean 1 or true for SLA-breached only
following boolean 1 or true for tickets you follow
sort_by string Sort field: created_at, updated_at, priority, status, subject
sort_dir string asc or desc (default: desc)
per_page integer Results per page, max 100 (default: 15)
page integer Page number (default: 1)

Response Format

List responses include data and pagination meta. Detail responses include data; mutations can also include a message. The following is an illustrative list response:

{
  "data": [],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 25,
    "total": 100
  }
}

Error responses

{
  "message": "Validation failed.",
  "errors": {
    "subject": ["Subject is required."]
  }
}
Status Meaning
200 Success
201 Created
400 Bad request (invalid JSON)
401 Unauthorized (missing/invalid token)
403 Forbidden (insufficient abilities)
404 Not found
422 Validation failed
429 Rate limited

Rate Limiting

API requests are rate-limited per token (default: 60 requests per minute). Requests passing API authentication receive rate-limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

When exceeded, a 429 response is returned with a Retry-After header.