Tickets

The Tickets API lets you manage IT support tickets programmatically — create tickets, list and filter them, fetch a single ticket, and update fields including status and priority.

Tickets created through this API are stored in Aurion. They are not sent to your ITSM tool (Freshservice, HaloITSM, ServiceNow, JSM), so external_provider, external_ticket_id and external_ticket_url are null on them. GET /tickets returns only tickets created through this API.

Create a Ticket

Requires the tickets:write scope.

curl -X POST "https://apps.aurionai.net/api/v1/tickets" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_xxxx" \
  -d '{
    "subject": "VPN not connecting",
    "description": "Unable to connect to corporate VPN since this morning.",
    "priority": "high",
    "requester_email": "alex@example.com",
    "metadata": { "category": "Network" }
  }'

Request body:

Field	Type	Required	Description
`subject`	string	yes	Ticket subject, 1–255 characters
`description`	string	yes	Ticket description, minimum 1 character
`status`	string	no	`open`, `pending`, `resolved`, `closed` (defaults to `open`)
`priority`	string	no	`low`, `medium`, `high`, `urgent`
`requester_email`	string	no	Email of the person the ticket is raised for
`metadata`	object	no	Arbitrary key/value data to attach to the ticket

There is no top-level category field — store free-form attributes such as a category inside metadata.

Response (201 Created):

{
  "id": "5c2e8f1a-3d4b-4e6f-9a1c-7b2d8e0f5a3c",
  "subject": "VPN not connecting",
  "description": "Unable to connect to corporate VPN since this morning.",
  "status": "open",
  "priority": "high",
  "requester_email": "alex@example.com",
  "external_provider": null,
  "external_ticket_id": null,
  "external_ticket_url": null,
  "metadata": { "category": "Network" },
  "created_at": "2026-02-20T14:30:00Z",
  "updated_at": "2026-02-20T14:30:00Z"
}

A 400 with body {"detail": "subject and description are required"} is returned when subject or description contains only whitespace. A malformed body (missing subject/description, subject over 255 chars, or a status/priority outside the values above) returns a 422 Pydantic validation error.

Get a Ticket

The ticket_id path parameter is a UUID. A non-UUID value returns 422, and an unknown ticket returns 404 with body {"detail": "Ticket not found"}.

curl "https://apps.aurionai.net/api/v1/tickets/5c2e8f1a-3d4b-4e6f-9a1c-7b2d8e0f5a3c" \
  -H "X-API-Key: itsm_sk_live_xxxx"

List Tickets

curl "https://apps.aurionai.net/api/v1/tickets?status=open&limit=10&offset=0" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `open`, `pending`, `resolved`, `closed`
`start_date`	string	ISO 8601 datetime — return tickets with `created_at >= start_date`
`end_date`	string	ISO 8601 datetime — return tickets with `created_at <= end_date`
`limit`	integer	Results per page (default: 20, min: 1, max: 100)
`offset`	integer	Number of results to skip (default: 0)

Response (200 OK):

{
  "tickets": [
    {
      "id": "5c2e8f1a-3d4b-4e6f-9a1c-7b2d8e0f5a3c",
      "subject": "VPN not connecting",
      "description": "Unable to connect to corporate VPN since this morning.",
      "status": "open",
      "priority": "high",
      "requester_email": "alex@example.com",
      "external_provider": null,
      "external_ticket_id": null,
      "external_ticket_url": null,
      "metadata": { "category": "Network" },
      "created_at": "2026-02-20T14:30:00Z",
      "updated_at": "2026-02-20T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

The list response uses a resource-named envelope (tickets), not data or items. See Pagination for details on paginating through results.

Update a Ticket

Use PATCH to change any subset of subject, description, status, priority, requester_email, or metadata. Omitted fields are left unchanged. Requires the tickets:write scope. An unknown ticket returns 404 with body {"detail": "Ticket not found"}.

curl -X PATCH "https://apps.aurionai.net/api/v1/tickets/5c2e8f1a-3d4b-4e6f-9a1c-7b2d8e0f5a3c" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "pending",
    "priority": "medium"
  }'

Close a Ticket

There is no dedicated close endpoint. Close a ticket by updating its status with PATCH:

curl -X PATCH "https://apps.aurionai.net/api/v1/tickets/5c2e8f1a-3d4b-4e6f-9a1c-7b2d8e0f5a3c" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Idempotency

POST /api/v1/tickets supports an Idempotency-Key header to prevent duplicate creation on retries:

curl -X POST "https://apps.aurionai.net/api/v1/tickets" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Idempotency-Key: idem_xxxx" \
  ...

If a request reuses an idempotency key within 1 hour (the cache TTL), the API returns the original response without creating a duplicate. The replayed request must carry an identical body — reusing the same key with a different payload returns 409 with body {"detail": "Idempotency key reused with a different payload"}.

The Ticket Object

Every ticket endpoint returns the same ticket shape:

Field	Type	Description
`id`	string	Ticket UUID
`subject`	string	Ticket subject
`description`	string	Ticket description
`status`	string	Current status (`open`, `pending`, `resolved`, `closed`)
`priority`	string \| null	Priority, if set
`requester_email`	string \| null	Requester email, if set
`external_provider`	string \| null	Always `null` — API tickets are not sent to your ITSM tool
`external_ticket_id`	string \| null	Always `null`
`external_ticket_url`	string \| null	Always `null`
`metadata`	object	Arbitrary key/value data attached to the ticket
`created_at`	string \| null	ISO 8601 creation timestamp
`updated_at`	string \| null	ISO 8601 last-update timestamp

Ticket Lifecycle

open → pending → resolved → closed
  ↑                           |
  └────── PATCH status ───────┘

Tickets progress through statuses. There is no dedicated transition endpoint — move a ticket between statuses (including reopening a closed one) by sending the target status to PATCH /tickets/:id.

Conversations — Omnichannel conversations (v2 API for the Aurion CS helpdesk)
Webhooks — Subscribe to ticket.* events
Custom Fields — Add custom data fields to tickets

Required Scopes

Scope	Endpoints
`tickets:read`	`GET /tickets`, `GET /tickets/:id`
`tickets:write`	`POST /tickets`, `PATCH /tickets/:id`

Tickets

On this page