Agent API & External Services

Authentication

Open Settings → Team & access → AI agents to create a managed AI agent, or Settings → API & agents to create a scoped key for an existing user. Copy the token once, store it outside the source repository, and send requests only over HTTPS.

The API evaluates both the selected token scopes and the permissions of the user who owns the token. A token cannot read or change tickets that its owner is not allowed to access.

Start every integration session

GET index.php?page=api&action=agent-docs — load the live, version-matched instructions and request contracts.
GET index.php?page=api&action=agent-me — verify the token identity, permissions, and scopes.

Do not use the token on the browser login page. Agent requests use the canonical index.php?page=api&action=agent-* route.

Common endpoints

GET agent-list-tickets — list and search visible tickets.
GET agent-get-ticket — load one visible ticket and its timeline.
POST agent-create-ticket — create a ticket.
POST agent-add-update — add a public comment or internal note without time.
POST agent-add-work-entry — add a linked comment and time entry atomically.
POST agent-plan-work-log and agent-apply-work-log-plan — preview and confirm structured multi-entry work logs.
POST agent-update-status — change a ticket status.
POST agent-log-time — add a standalone time entry.

The complete endpoint list, fields, and current constraints come from agent-docs; do not copy an older request schema into an integration.

Request example

FOXDESK_BASE_URL=https://helpdesk.example.com
FOXDESK_API_TOKEN=fdx_replace_with_token_from_settings

curl -fsS -X POST \
  "$FOXDESK_BASE_URL/index.php?page=api&action=agent-add-update" \
  -H "Authorization: Bearer $FOXDESK_API_TOKEN" \
  -H "Idempotency-Key: comment-ticket-542-20260729-01" \
  -H "Content-Type: application/json" \
  --data '{
    "ticket_id": 542,
    "content": "The nightly backup completed successfully.",
    "is_internal": true
  }'

Use a unique Idempotency-Key on every write request. Begin with read-only scopes, add write scopes only for the intended workflow, and use the plan/apply workflow when a user asks for a structured work log.