Skip to content

api.md

Latest commit

 

History

History
117 lines (80 loc) · 4.84 KB

api.md

File metadata and controls

117 lines (80 loc) · 4.84 KB
Raw

Agent API Reference

Underlying REST API that the support CLI wraps. Base URL defaults to https://support.virtuals.io; override via ACP_BASE. Auth is Authorization: Bearer acp_live_....

Consult this file when you need to call the API directly (for example, from code that can't shell out to the CLI).

Conventions

  • All request bodies are JSON (Content-Type: application/json).
  • Mutations accept Idempotency-Key: <unique> as a header and version in the body.
  • Keys are scoped to (token, METHOD path) for 24 hours — reusing a key across different endpoints returns 422.
  • Error responses have shape { "error": "<message>" }. Some also include currentVersion on 409 version mismatches.
  • A 404 may mean "does not exist" or "exists but on another team" — identical response either way.

GET /api/agent/me

Returns the admin and token bound to the bearer. CLI: support me.

{
  "admin": { "id": 7, "username": "alice", "email": "...", "agentTag": "Axelrod", "teamId": 3, "role": "admin" },
  "token": { "id": 42, "name": "prod-integration", "createdAt": "...", "lastUsedAt": "..." }
}

GET /api/agent/tickets

Query: status, jobId (both optional). CLI: support ticket list.

{ "count": 2, "tickets": [ { "id": "FB123", "status": "pending", "version": 1, "...": "..." } ] }

GET /api/agent/tickets/:id

Full ticket. CLI: support ticket get.

GET /api/agent/tickets/:id/comments

Returns the user-facing comment thread. CLI: support ticket comments.

GET /api/agent/tickets/:id/audit

Returns the audit log; each entry includes tokenId and sourceIp. CLI: support ticket audit.

POST /api/agent/tickets/:id/status

CLI: support ticket status <id> <new_status> [--message] [--tx-hash].

Field Type Req Notes
status string yes One of pending, in-progress, resolved, refunded, rejected
message string no User-visible; appended to adminNotes. Max 5000 chars.
transactionHash string no For refunds. Max 255 chars.
version number no Optimistic concurrency.

Same-status returns { success: true, ticket, noChange: true }. Terminal status transitions return 409. Emails the user when ticket.contactMethod === 'email'.

POST /api/agent/tickets/:id/comment

CLI: support ticket comment <id> <body> [--email].

Field Type Req Notes
body string yes Plain text. Max 5000 chars.
sendEmail boolean no True to also email the user.

Response includes emailSent: boolean reflecting what actually happened — an email with sendEmail: true but no contactMethod=email/username persists the comment but returns emailSent: false.

Email-on-terminal returns 409.

PATCH /api/agent/tickets/:id/notes

CLI: support ticket notes <id> <text>.

Field Type Req Notes
notes string yes Max 5000 chars. Pass "" to clear.
version number no Optimistic concurrency.

Never emailed. Replaces the field — read first if appending.

POST /api/agent/tickets/:id/assign

CLI: support ticket assign <id> --reason <r> [--team <t>] [--admin <u>].

Field Type Req Notes
toTeam string one-of Destination team name
toAdminUsername string one-of Must belong to toTeam (or be on ALL)
reason string yes Required. Max 500 chars. Appended to notes.
version number no Optimistic concurrency.

Rate-limited to 10/hour per token. After reassignment the ticket is invisible to this token.

Rate limits (per token)

Limit Default Env override
All requests / minute 30 AGENT_API_RATE_LIMIT_PER_MINUTE
User-facing emails / minute 5 AGENT_API_EMAIL_LIMIT_PER_MINUTE
Reassigns / hour 10 AGENT_API_REASSIGN_LIMIT_PER_HOUR

Audit actions

status_change, comment_added, comment_added_email, notes_update, assigned, assigned_to_admin.