API Reference Overview¶

This reference provides detailed information about all TopTickets API endpoints.

Base URL¶

All API requests should be made to:

https://api.toptickets.app/v1

Request Format¶

Headers¶

All requests must include:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Bodies¶

For POST and PATCH requests, send JSON in the request body:

{
  "field_name": "value"
}

Response Format¶

All responses are returned as JSON. Successful responses include the requested data directly.

Success Response (Single Object)¶

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Example",
  "created_at": "2025-01-15T10:30:00Z"
}

Success Response (List)¶

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Item 1"
  },
  {
    "id": "456e7890-e12b-34c5-d678-901234567890",
    "name": "Item 2"
  }
]

Error Response¶

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes¶

Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`204`	No Content - Request succeeded (typically for DELETE)
`400`	Bad Request - Invalid request body or parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Valid key but insufficient permissions
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server-side error

Pagination¶

List endpoints support pagination using offset and limit parameters:

GET /v1/tickets?offset=0&limit=50

Parameter	Type	Default	Max	Description
`offset`	integer	0	-	Number of items to skip
`limit`	integer	100	500	Maximum items to return

Example¶

# Get first 50 tickets
curl "https://api.toptickets.app/v1/tickets?limit=50"

# Get next 50 tickets
curl "https://api.toptickets.app/v1/tickets?offset=50&limit=50"

Filtering¶

Many list endpoints support filtering via query parameters. See each resource's documentation for available filters.

Example: Filter Tickets¶

# Get high priority open tickets
curl "https://api.toptickets.app/v1/tickets?status=open&priority=high"

# Search for tickets
curl "https://api.toptickets.app/v1/tickets?search=login%20issue"

Data Types¶

UUIDs¶

All resource IDs are UUIDs in standard format:

550e8400-e29b-41d4-a716-446655440000

Timestamps¶

All timestamps are in ISO 8601 format with UTC timezone:

2025-01-15T10:30:00Z

Enums¶

Many fields accept specific values. Invalid values return a 422 error.

Ticket Status: new, open, pending, resolved, closed

Ticket Priority: low, medium, high, urgent

Available Resources¶

Resource	Description	Documentation
Tickets	Support tickets	Tickets
Comments	Ticket comments and notes	Comments
Attachments	File attachments on tickets	Attachments
Customers	Customer records	Customers
Teams	Agent teams	Teams
Users	Agent user accounts	Users

Rate Limiting¶

Requests are rate limited based on your API key type:

Key Type	Limit
`tt_admin_`	2,000/minute
`tt_ro_`	200/minute

See Rate Limits for details.

Versioning¶

The API version is included in the URL path (/v1/). Breaking changes will be released under a new version number.

OpenAPI Specification¶

The full OpenAPI specification is available at:

https://api.toptickets.app/v1/openapi.json

Interactive API documentation is available at:

https://api.toptickets.app/docs