TicketingSystemOpenAPI JSON

API reference v1.0.0

Read and change a workspace’s tickets, contacts and issues, and read its published help-center articles. JSON over HTTPS at /api/v1.

Keys and scopes

Workspace owners and admins make keys under Settings → API keys. Send one on every request as Authorization: Bearer tsk_…. A key acts as the member who made it: it may do what its scopes allow and that member’s role still permits, and it stops working if they leave. The API comes with the Pro and Business plans.

Limits

Each plan has a daily allowance of requests per workspace (UTC days; see pricing), and each key may make 120 requests a minute. Over either, the answer is 429 with a Retry-After header in seconds.

Pages

Lists answer { data, next_cursor }. Pass next_cursor back as cursor until it is null. limit is 1 to 100 (default 25).

Retries

Send an Idempotency-Key header (any unique string) with a POST or PATCH to retry it safely. The same key with the same request within 24 hours replays the first answer, marked Idempotent-Replayed: true, instead of acting twice. While the first is still running a retry gets 409; the same key with a different request gets 422. Server errors are not remembered, so retry them with the same key.

Errors

Every error answers { "error": { "code", "message" } }. Codes are stable; messages are for people. Anything that belongs to another workspace is a 404, never a 403.

Tickets

List tickets

GET/api/v1/ticketstickets:read

Most recently updated first. Spam and deleted tickets are left out unless status asks for them.

Parameters

  • cursorquery, string

    next_cursor from the previous page.

  • limitquery, integer

    Page size, 1 to 100.

  • statusquery, "new" | "open" | "pending" | "on_hold" | "solved" | "closed" | "spam" | "deleted"

200: A page of tickets. (TicketPage)

Fields
  • dataTicket[]required
  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last.

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 429 Over the daily or per-minute limit. See Retry-After.

Create a ticket

POST/api/v1/ticketstickets:write

Filed on the requester's behalf by the key's creator, with the body as its first public message. Counts toward the plan's tickets per month.

Parameters

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • subjectstringrequired

    Up to 250 characters.

  • bodystringrequired

    Up to 50000 characters.

  • requesterobjectrequired
    • emailstringrequired

      Up to 254 characters.

    • namestring

      Up to 120 characters.

  • priority"low" | "normal" | "high" | "urgent"

    Default "normal".

  • assignee_idstring (uuid) | null

201: The new ticket. (Ticket)

Fields
  • idstring (uuid)required
  • numberintegerrequired
  • subjectstringrequired
  • status"new" | "open" | "pending" | "on_hold" | "solved" | "closed" | "spam" | "deleted"required
  • priority"low" | "normal" | "high" | "urgent"required
  • type"question" | "incident" | "problem" | "task"required
  • channel"web" | "email" | "portal" | "api"required
  • urlstring (uri)required

    The ticket in the agent workspace.

  • requesterobjectrequired
    • emailstringrequired
    • namestring | nullrequired
  • assigneeobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • teamobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • tagsstring[]required
  • custom_fieldsobject[]required
    • idstring (uuid)required
    • labelstringrequired
    • valuestring | number | booleanrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 409 Conflicts with the current state, or an Idempotency-Key still in use.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

Get a ticket

GET/api/v1/tickets/{number}tickets:read

Parameters

  • numberpath, integerrequired

    1 to 2147483647.

200: The ticket. (Ticket)

Fields
  • idstring (uuid)required
  • numberintegerrequired
  • subjectstringrequired
  • status"new" | "open" | "pending" | "on_hold" | "solved" | "closed" | "spam" | "deleted"required
  • priority"low" | "normal" | "high" | "urgent"required
  • type"question" | "incident" | "problem" | "task"required
  • channel"web" | "email" | "portal" | "api"required
  • urlstring (uri)required

    The ticket in the agent workspace.

  • requesterobjectrequired
    • emailstringrequired
    • namestring | nullrequired
  • assigneeobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • teamobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • tagsstring[]required
  • custom_fieldsobject[]required
    • idstring (uuid)required
    • labelstringrequired
    • valuestring | number | booleanrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

Update a ticket

PATCH/api/v1/tickets/{number}tickets:write

Status, priority, assignee and team; send only what changes. Changing the assignee or team needs a creator whose role may assign tickets.

Parameters

  • numberpath, integerrequired

    1 to 2147483647.

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • status"open" | "pending" | "on_hold" | "solved"
  • priority"low" | "normal" | "high" | "urgent"
  • assignee_idstring (uuid) | null
  • team_idstring (uuid) | null

200: The ticket as it is now. (Ticket)

Fields
  • idstring (uuid)required
  • numberintegerrequired
  • subjectstringrequired
  • status"new" | "open" | "pending" | "on_hold" | "solved" | "closed" | "spam" | "deleted"required
  • priority"low" | "normal" | "high" | "urgent"required
  • type"question" | "incident" | "problem" | "task"required
  • channel"web" | "email" | "portal" | "api"required
  • urlstring (uri)required

    The ticket in the agent workspace.

  • requesterobjectrequired
    • emailstringrequired
    • namestring | nullrequired
  • assigneeobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • teamobject | nullrequired
    • idstring (uuid)required
    • namestringrequired
  • tagsstring[]required
  • custom_fieldsobject[]required
    • idstring (uuid)required
    • labelstringrequired
    • valuestring | number | booleanrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 409 Conflicts with the current state, or an Idempotency-Key still in use.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

List a ticket's messages

GET/api/v1/tickets/{number}/messagestickets:read

Oldest first, public replies and internal notes alike.

Parameters

  • numberpath, integerrequired

    1 to 2147483647.

  • cursorquery, string

    next_cursor from the previous page.

  • limitquery, integer

    Page size, 1 to 100.

200: A page of messages. (MessagePage)

Fields
  • dataMessage[]required
  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last.

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

Add a reply or note

POST/api/v1/tickets/{number}/messagestickets:write

A public reply (emailed to the requester and CCs, as from the agent workspace) or an internal note, written as the key's creator.

Parameters

  • numberpath, integerrequired

    1 to 2147483647.

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • bodystringrequired

    Up to 50000 characters.

  • visibility"public" | "internal"

    Default "public".

201: The new message. (Message)

Fields
  • idstring (uuid)required
  • visibility"public" | "internal"required
  • author_type"agent" | "contact" | "system" | "api"required
  • author_namestringrequired
  • body_textstringrequired
  • created_atstring (date-time)required
  • attachmentsobject[]required
    • idstring (uuid)required
    • file_namestringrequired
    • content_typestringrequired
    • size_bytesintegerrequired

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 409 Conflicts with the current state, or an Idempotency-Key still in use.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

List assignable users

GET/api/v1/userstickets:read

Members who can be assigned tickets, for assignee_id.

200: Every assignable member.

Fields
  • dataUser[]required

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 429 Over the daily or per-minute limit. See Retry-After.

Contacts

List contacts

GET/api/v1/contactscontacts:read

By email address. query matches part of a name or address.

Parameters

  • cursorquery, string

    next_cursor from the previous page.

  • limitquery, integer

    Page size, 1 to 100.

  • queryquery, string

    Up to 100 characters.

200: A page of contacts. (ContactPage)

Fields
  • dataContact[]required
  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last.

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 429 Over the daily or per-minute limit. See Retry-After.

Create a contact

POST/api/v1/contactscontacts:write

Parameters

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • emailstringrequired

    Up to 254 characters.

  • namestring

    Up to 120 characters.

201: The new contact. (Contact)

Fields
  • idstring (uuid)required
  • emailstringrequired
  • namestringrequired
  • company_namestring | nullrequired
  • created_atstring (date-time)required

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 409 Conflicts with the current state, or an Idempotency-Key still in use.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

Get a contact

GET/api/v1/contacts/{id}contacts:read

Parameters

  • idpath, string (uuid)required

    Up to 100 characters.

200: The contact. (Contact)

Fields
  • idstring (uuid)required
  • emailstringrequired
  • namestringrequired
  • company_namestring | nullrequired
  • created_atstring (date-time)required

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

Update a contact

PATCH/api/v1/contacts/{id}contacts:write

Name and company. company_name null or empty detaches the contact from its company. The address can't change.

Parameters

  • idpath, string (uuid)required

    Up to 100 characters.

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • namestring

    Up to 120 characters.

  • company_namestring | null

    Up to 120 characters.

200: The contact as it is now. (Contact)

Fields
  • idstring (uuid)required
  • emailstringrequired
  • namestringrequired
  • company_namestring | nullrequired
  • created_atstring (date-time)required

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 409 A request with the same Idempotency-Key is still running.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 The Idempotency-Key was used with a different request.
  • 429 Over the daily or per-minute limit. See Retry-After.

Issues

List projects

GET/api/v1/projectsissues:read

200: Every project.

Fields
  • dataProject[]required

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 429 Over the daily or per-minute limit. See Retry-After.

Get a project

GET/api/v1/projects/{key}issues:read

With its statuses in board order, for status_id.

Parameters

  • keypath, stringrequired

    Up to 20 characters.

200: The project. (ProjectDetail)

Fields

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

List a project's issues

GET/api/v1/issuesissues:read

By number, oldest first. Epics included.

Parameters

  • cursorquery, string

    next_cursor from the previous page.

  • limitquery, integer

    Page size, 1 to 100.

  • projectquery, stringrequired

    Project key.

200: A page of issues. (IssuePage)

Fields
  • dataIssueSummary[]required
  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last.

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

Create an issue

POST/api/v1/issuesissues:write

Reported by the key's creator. Without status_id it starts in the project's first status.

Parameters

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • projectstringrequired

    Project key. Up to 20 characters.

  • titlestringrequired

    Up to 250 characters.

  • descriptionstring

    Default "". Up to 20000 characters.

  • type"task" | "bug" | "story" | "epic"

    Default "task".

  • priority"low" | "normal" | "high" | "urgent"

    Default "normal".

  • status_idstring (uuid)
  • assignee_idstring (uuid) | null
  • parent_keystring | null

    Up to 40 characters.

  • pointsinteger | null

    0 to 100.

201: The new issue. (Issue)

Fields

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 409 A request with the same Idempotency-Key is still running.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

Get an issue

GET/api/v1/issues/{key}issues:read

Parameters

  • keypath, stringrequired

    Up to 40 characters.

200: The issue. (Issue)

Fields

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.

Update an issue

PATCH/api/v1/issues/{key}issues:write

Send only what changes. A new status_id moves the issue to the bottom of that column, as a drop on the board would, after the other fields are saved.

Parameters

  • keypath, stringrequired

    Up to 40 characters.

  • Idempotency-Keyheader, string

    Retry safely: the same key and request within 24 hours replays the first answer.

Body

  • titlestring

    Up to 250 characters.

  • descriptionstring

    Up to 20000 characters.

  • type"task" | "bug" | "story" | "epic"
  • priority"low" | "normal" | "high" | "urgent"
  • status_idstring (uuid)
  • assignee_idstring (uuid) | null
  • parent_keystring | null

    Up to 40 characters.

  • pointsinteger | null

    0 to 100.

200: The issue as it is now. (Issue)

Fields

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 409 A request with the same Idempotency-Key is still running.
  • 413 The body is over 262144 bytes.
  • 415 The body is not application/json.
  • 422 Well formed but not allowed: a rule of the workspace refuses it.
  • 429 Over the daily or per-minute limit. See Retry-After.

Knowledge base

List published articles

GET/api/v1/kb/articleskb:read

By slug.

Parameters

  • cursorquery, string

    next_cursor from the previous page.

  • limitquery, integer

    Page size, 1 to 100.

200: A page of articles. (ArticlePage)

Fields
  • dataArticleSummary[]required
  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last.

Errors

  • 400 The request is malformed or fails validation.
  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 429 Over the daily or per-minute limit. See Retry-After.

Get a published article

GET/api/v1/kb/articles/{slug}kb:read

Parameters

  • slugpath, stringrequired

    Up to 100 characters.

200: The article. (Article)

Fields

Errors

  • 401 Missing, malformed, unknown or revoked API key.
  • 403 The key lacks the scope, or the plan does not include the API.
  • 404 Not found, including anything that belongs to another workspace.
  • 429 Over the daily or per-minute limit. See Retry-After.