Response Format

Every AGNT API response follows a predictable shape. No guessing, no surprises.

Success Responses

json

{
  "ok": true,
  "resourceName": [...],
  "page": 1,
  "perPage": 20,
  "total": 47
}

resourceName is the plural name of the resource — chats, tasks, certificates, prompts, etc. It varies by endpoint.

json

{
  "ok": true,
  "resourceName": { ... }
}

Same deal — resourceName matches the endpoint's resource. A GET /chats/:id returns { ok: true, chat: { ... } }.

json

{
  "ok": true,
  "resourceName": {
    "id": "the-deleted-id",
    "message": "Resource deleted successfully"
  }
}

Confirms the deletion with the ID of what was removed.

json

{
  "error": "Human-readable error message",
  "error_code": "ERROR_TYPE"
}

error is a plain-English description of what went wrong. error_code is a machine-readable constant you can switch on in code.

Code	Meaning	When
200	OK	Successful read or update
201	Created	Successful resource creation
400	Bad Request	Invalid input, missing required fields, malformed body
401	Unauthorized	Missing or invalid JWT, expired token
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn't exist or you don't have access
409	Conflict	Resource conflict (e.g., chat already being processed)
500	Internal Server Error	Something broke on our end

If you get a 401, check your JWT. If you get a 403, check your permissions. If you get a 500, that's on us — retry after a moment.

List endpoints accept these query parameters:

Parameter	Default	Description
`page`	1	Page number (1-indexed)
`perPage`	20	Results per page (max 100 typically)

Response always includes page, perPage, and total so you can calculate total pages and build pagination UI.

GET https://api.agnt.ai/chats?page=2&perPage=50

json

{
  "ok": true,
  "chats": [...],
  "page": 2,
  "perPage": 50,
  "total": 147
}

Page past the end and you get an empty array with the correct total. No errors.