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.

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	Initial status (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": "freshservice",
  "external_ticket_id": "1042",
  "external_ticket_url": "https://example.freshservice.com/a/tickets/1042",
  "metadata": { "category": "Network" },
  "created_at": "2026-02-20T14:30:00Z",
  "updated_at": "2026-02-20T14:30:00Z"
}

A 400 with body {"detail": "<validation message>"} is returned if the underlying ITSM provider rejects the ticket (e.g. a mandatory field is missing). A malformed body (missing subject/description, or subject over 255 chars) 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": "freshservice",
      "external_ticket_id": "1042",
      "external_ticket_url": "https://example.freshservice.com/a/tickets/1042",
      "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	Backing ITSM provider (e.g. `freshservice`)
`external_ticket_id`	string \| null	Ticket ID in the backing ITSM provider
`external_ticket_url`	string \| null	Deep link to the ticket in the backing provider
`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