JSON API

Routes, form requests, controllers, role-aware resources, query-builder list filters, a policy, rate limits and guest endpoints — off until you switch them on:

TICKETS_ROUTES=on

• Prefix tickets.routes.prefix (api), route names tickets.*, middleware tickets.routes.middleware (['api', 'auth', 'throttle:tickets-api']).
• {ticket} is the reference ([A-Z][A-Z0-9]{0,9}-[0-9]+). Controllers look tickets up through the model seam, so the API works without SubstituteBindings and with a swapped ticket model. A soft-deleted ticket is 404, except on restore.
• To change a route, publish routes/tickets.php (--tag=tickets-routes); the published copy replaces the package’s for good.

With Sanctum

// config/tickets.php
'routes' => [
    'enabled' => env('TICKETS_ROUTES') ?: 'off',
    'middleware' => ['api', 'auth:sanctum', 'throttle:tickets-api'],
    // …
],

Any guard works the same way (auth:api, …). Without an auth middleware every endpoint would answer anonymous callers — tickets:doctor warns.

Rate limits

Defined only with the routes on, applied only while their throttle: middleware is listed: tickets-api allows tickets.routes.rate_limit (120) requests a minute per signed-in user (per IP otherwise); tickets-guest allows tickets.routes.guest.rate_limit (30) a minute per IP and ticket.

Routes

There is no category-restore endpoint — use Tickets::categories()->restore().

Filing a ticket

POST /api/tickets
{
  "subject": "Printer on floor 3 is jammed",
  "description": "Paper jam error E-102.",
  "category_id": 4,
  "priority": "high",
  "channel": "web",
  "fields": {"asset_tag": "PRN-0042"},
  "project": {"type": "project", "id": 1}
}

Self-service files for the signed-in user. subject (≤ 255), description, category_id, priority, channel, project and fields (requester-editable ones for a non-agent) are open to anyone who may file. requester, guest (fields, instead of a requester), assignee, due_at (after now), tags and watchers are agent-only inputs; naming an assignee other than yourself needs the assign ability. Morph inputs are {type: alias, id} with an alias from the allow-lists — a class name, an unknown alias or a key that matches no record is 422. Attachments are multipart attachments[].

Bulk

POST /api/tickets/bulk
{"action": "transition", "tickets": ["TCK-1", "TCK-2"], "transition": "resolve", "payload": {"resolution": "Fixed"}}

action is assign (assignee or claim: true), unassign, transition (transition, reason?, payload?), priority (priority) or tags (tags.attach / tags.detach, up to 50 names each) — at most tickets.routes.bulk.max (100) distinct references. Each ticket runs on its own policy check and transaction, and one failing never stops the others:

{"data": [
  {"ticket": "TCK-1", "ok": true, "status": 200},
  {"ticket": "TCK-2", "ok": false, "status": 422, "code": "ticket_transition_denied", "message": "…"}
]}

A per-ticket validation failure reports code validation_failed; every other failure carries the code of the error table (ticket_not_found for an unknown reference or one the user may not view). assign without assignee and without claim: true is a 422 for the whole request.

Request bodies

Uploads (attachments[], file) follow the bucket’s own mime types and size cap through media-library — tickets.attachments.* for ticket files, comments’ comments.media.* for message files — at most 10 files per request.

Admin endpoints

Translatable text (name, description, label, help, an option label) is a string in the current locale or a locale map ({"en": "Hardware", "sk": "Hardvér"}). Morph inputs are {type: alias, id}; list filters take alias:key.

Resources

Role-aware: the viewer is an agent (the agent ability and the agent scope allow them on this ticket), the requester, a participant (a watcher) or a guest (through a signed link).

People (requester, assignee, author, actor, watcher) show as their alias from the allow-lists, never a class name: agents get {type, id, name}; anyone else {type, name}, with name: null for a guest who is not themselves. Requesters never see internal notes, held replies, internal activity, last_activity_at, tags or watcher lists, and a ticket’s host meta never appears in any resource. Enum values come with their translated label and colour, so a client renders a badge without its own lookup tables:

"status":   {"value": "pending", "label": "Waiting on requester", "category": "waiting", "color": "amber"},
"priority": {"value": "high", "label": "High", "weight": 30, "color": "orange"},
"channel":  {"value": "web", "label": "Web", "color": "blue"}

Response bodies

Ticket list — filters, sorts, paging

GET /tickets is query-builder-for-laravel over visibleTo($user); every filter is one of the Ticket query scopes:

The agent-only filters — tag, requester=alias:key and a field that is not requester-visible — match only the tickets the agent scope lets the viewer work on. An unknown filter or sort is 400 under the host’s query-builder.mode.unknown_filter = reject (the default); ignore drops it.

Sorts: created_at, updated_at, due_at, number, priority (the enum weights) and, for agents, last_activity_at. The default is -last_activity_at for agents and -created_at otherwise. Paging: per_page (default 20, at most tickets.routes.max_per_page) and page; the list eager-loads category, assignee, requester, tags and message counts in a fixed number of queries.

Errors

Mapped in the package’s controllers — never in your exception handler — to {message, code}. Configuration errors stay 500: they are the host’s to fix, never the client’s.