> For the complete documentation index, see [llms.txt](https://support.suptask.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.suptask.com/integrations-automations-and-workflows/api.md).

# Suptask API

Learn how to use and integrate with the Suptask API

### Overview

Suptask offers an open API that enables you to integrate programmatically and automate your ticketing process.

### API Definition

Review the OpenAPI v3 definition below.

## Create a ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Creates a ticket through a form. For Slack forms the ticket is posted in\
> \`requesterChannel\`. For email forms the ticket is an email ticket and\
> \`requesterEmail\` is required instead.\
> \
> \*\*Requester resolution\*\* (Slack forms): \`requester\` → \`requesterEmail\` → the token owner.\
> An email that does not match a workspace member falls back to the token owner.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"CreateTicketRequest":{"allOf":[{"$ref":"#/components/schemas/TicketFields"},{"type":"object","required":["formId","description"],"properties":{"formId":{"type":"string","format":"uuid","description":"The form to create the ticket with."},"description":{"type":"string"},"requesterChannel":{"type":"string","description":"Slack channel ID to post the ticket in; must be one of the form's channels.\nRequired for Slack forms, not used for email forms.\n"},"ts":{"type":"string","description":"Create the ticket on an existing Slack message in `requesterChannel` (its\nmessage timestamp) instead of posting a new message. Fails if the message\ndoes not exist.\n"}}}]},"TicketFields":{"type":"object","description":"Properties shared by create and update.","properties":{"priority":{"type":"string","nullable":true,"description":"Priority name as configured on the form."},"status":{"type":"string","description":"Status name as configured on the form."},"assignee":{"type":"string","nullable":true,"description":"Slack member ID of the assignee. Takes precedence over `assigneeEmail`."},"assigneeEmail":{"type":"string","format":"email","description":"Assign by email address of a workspace member."},"requester":{"type":"string","description":"Slack member ID of the requester. Takes precedence over `requesterEmail`."},"requesterEmail":{"type":"string","format":"email","description":"Requester's email address. On email forms this is the requester (required);\non Slack forms it is matched to a workspace member.\n"},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/FieldValue"}},"dueDate":{"type":"string","format":"date","nullable":true},"tags":{"type":"array","nullable":true,"items":{"type":"string"}}}},"FieldValue":{"type":"object","required":["fieldId","value"],"properties":{"fieldId":{"type":"string","format":"uuid","description":"The custom field's UUID."},"value":{"description":"Text value, a list of values for multi-select fields, or `null` to clear.","oneOf":[{"type":"string","nullable":true},{"type":"array","items":{"type":"string"}}]}}},"TicketRecord":{"type":"object","description":"The created or updated ticket. Only the properties listed here are guaranteed;\nuse `GET /ticket/{ticket}` with `ticketNumber` for the full ticket.\n","properties":{"id":{"type":"string","format":"uuid","description":"The ticket UUID, used by the update, delete, reply and approval endpoints."},"ticketNumber":{"type":"integer"},"status":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"validation":{"type":"array","description":"What failed validation. Intended for debugging; the format may change.","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket":{"post":{"tags":["Tickets"],"summary":"Create a ticket","operationId":"createTicket","description":"**Scope:** `tickets:write`\n\nCreates a ticket through a form. For Slack forms the ticket is posted in\n`requesterChannel`. For email forms the ticket is an email ticket and\n`requesterEmail` is required instead.\n\n**Requester resolution** (Slack forms): `requester` → `requesterEmail` → the token owner.\nAn email that does not match a workspace member falls back to the token owner.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTicketRequest"}}}},"responses":{"201":{"description":"Ticket created. Returns the stored ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketRecord"}}}},"400":{"description":"Invalid payload — schema validation, an unknown field ID for the form, an invalid\nstatus/priority/tag/assignee, a requester from another workspace, or\n`requesterEmail` missing on an email form.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Form, workspace or requester user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Get a ticket by ticket number

> \*\*Scope:\*\* \`tickets:read\`\
> \
> \*\*Rate limit:\*\* 100 requests per 15 minutes per user. Current usage is returned in\
> the \`X-RateLimit-\*\` headers.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window resets (ISO 8601)","schema":{"type":"string","format":"date-time"}}},"schemas":{"Ticket":{"type":"object","required":["id","ticketNumber","teamId","status","description","requesterId","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"ticketNumber":{"type":"string","description":"Ticket number, as a string."},"teamId":{"type":"string"},"queueId":{"type":"string","description":"The inbox the ticket belongs to."},"formId":{"type":"string","format":"uuid"},"status":{"type":"string"},"priority":{"type":"string","nullable":true},"description":{"type":"string"},"assignee":{"type":"string","nullable":true,"description":"Slack member ID of the assignee."},"requesterId":{"type":"string","description":"Slack member ID of the requester."},"requester":{"type":"string","description":"Requester display name."},"tags":{"type":"array","nullable":true,"items":{"type":"string"}},"customFields":{"type":"array","items":{"type":"object","properties":{"fieldName":{"type":"string","description":"Field label."},"value":{"description":"String, or array of strings for multi-select fields.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}},"dueDate":{"type":"string","format":"date"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"closedDate":{"type":"string","format":"date-time","nullable":true},"organization":{"type":"string","nullable":true},"source":{"type":"string","description":"Where the ticket came from (e.g. `slack`, `email`, `api`)."},"archived":{"type":"boolean"},"messageRequesterChannel":{"type":"string"},"messageResponderChannel":{"type":"string"},"requesterThreadPermalink":{"type":"string"},"responderThreadPermalink":{"type":"string"},"summaryTitle":{"type":"string","nullable":true},"summaryProblem":{"type":"string","nullable":true},"summarySolution":{"type":"string","nullable":true},"csatRating":{"type":"integer","nullable":true,"minimum":1,"maximum":5},"csatComment":{"type":"string","nullable":true},"extTicketRef":{"type":"array","nullable":true,"description":"IDs of linked external tickets.","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/{ticket}":{"get":{"tags":["Tickets"],"summary":"Get a ticket by ticket number","operationId":"getTicketByNumber","description":"**Scope:** `tickets:read`\n\n**Rate limit:** 100 requests per 15 minutes per user. Current usage is returned in\nthe `X-RateLimit-*` headers.\n","parameters":[{"name":"ticket","in":"path","required":true,"description":"The numeric **ticket number**, as shown in Slack and the web app (e.g. `2075`).","schema":{"type":"string","pattern":"^\\d+$"}}],"responses":{"200":{"description":"Ticket found","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"description":"Ticket number is not numeric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No ticket with this number in your workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Delete a ticket

> \*\*Scope:\*\* \`tickets:delete\`\
> \
> The token owner must be an agent of the ticket's inbox \*\*and\*\* a Suptask or Slack\
> admin. The ticket's Slack messages are removed as well.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"parameters":{"TicketId":{"name":"ticket","in":"path","required":true,"description":"The ticket's **UUID** (`id` on the ticket).","schema":{"type":"string","format":"uuid"}}},"schemas":{"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/{ticket}":{"delete":{"tags":["Tickets"],"summary":"Delete a ticket","operationId":"deleteTicket","parameters":[{"$ref":"#/components/parameters/TicketId"}],"description":"**Scope:** `tickets:delete`\n\nThe token owner must be an agent of the ticket's inbox **and** a Suptask or Slack\nadmin. The ticket's Slack messages are removed as well.\n","responses":{"200":{"description":"Ticket deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"ticketId":{"type":"string","format":"uuid"},"ticketNumber":{"type":"integer"}}}}}},"400":{"description":"Ticket not found in your workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing scope, or the token owner may not delete this ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Update a ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Send only the properties you want to change; at least one of \`description\`,\
> \`priority\`, \`status\`, \`assignee\`, \`requester\`, \`tags\`, \`dueDate\` or \`customFields\`\
> is required. \`null\` clears \`description\`, \`priority\`, \`assignee\` and \`dueDate\`.\
> \
> Closing a ticket whose form has fields marked \*required before close\* fails with\
> \`400\` and \`internalCode: REQUIRED\_FIELDS\_MISSING\_BEFORE\_CLOSE\` until those fields\
> are set (they can be set in the same request).<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"parameters":{"TicketId":{"name":"ticket","in":"path","required":true,"description":"The ticket's **UUID** (`id` on the ticket).","schema":{"type":"string","format":"uuid"}}},"schemas":{"UpdateTicketRequest":{"allOf":[{"$ref":"#/components/schemas/TicketFields"},{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"New description; `null` clears it."}}}],"minProperties":1},"TicketFields":{"type":"object","description":"Properties shared by create and update.","properties":{"priority":{"type":"string","nullable":true,"description":"Priority name as configured on the form."},"status":{"type":"string","description":"Status name as configured on the form."},"assignee":{"type":"string","nullable":true,"description":"Slack member ID of the assignee. Takes precedence over `assigneeEmail`."},"assigneeEmail":{"type":"string","format":"email","description":"Assign by email address of a workspace member."},"requester":{"type":"string","description":"Slack member ID of the requester. Takes precedence over `requesterEmail`."},"requesterEmail":{"type":"string","format":"email","description":"Requester's email address. On email forms this is the requester (required);\non Slack forms it is matched to a workspace member.\n"},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/FieldValue"}},"dueDate":{"type":"string","format":"date","nullable":true},"tags":{"type":"array","nullable":true,"items":{"type":"string"}}}},"FieldValue":{"type":"object","required":["fieldId","value"],"properties":{"fieldId":{"type":"string","format":"uuid","description":"The custom field's UUID."},"value":{"description":"Text value, a list of values for multi-select fields, or `null` to clear.","oneOf":[{"type":"string","nullable":true},{"type":"array","items":{"type":"string"}}]}}},"TicketRecord":{"type":"object","description":"The created or updated ticket. Only the properties listed here are guaranteed;\nuse `GET /ticket/{ticket}` with `ticketNumber` for the full ticket.\n","properties":{"id":{"type":"string","format":"uuid","description":"The ticket UUID, used by the update, delete, reply and approval endpoints."},"ticketNumber":{"type":"integer"},"status":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"validation":{"type":"array","description":"What failed validation. Intended for debugging; the format may change.","items":{"type":"object"}}}},"RequiredFieldsMissingError":{"type":"object","properties":{"error":{"type":"string"},"internalCode":{"type":"string","enum":["REQUIRED_FIELDS_MISSING_BEFORE_CLOSE"]},"message":{"type":"string"},"missingFields":{"type":"array","description":"Labels of the fields that must be set before closing","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/{ticket}":{"patch":{"tags":["Tickets"],"summary":"Update a ticket","operationId":"updateTicket","parameters":[{"$ref":"#/components/parameters/TicketId"}],"description":"**Scope:** `tickets:write`\n\nSend only the properties you want to change; at least one of `description`,\n`priority`, `status`, `assignee`, `requester`, `tags`, `dueDate` or `customFields`\nis required. `null` clears `description`, `priority`, `assignee` and `dueDate`.\n\nClosing a ticket whose form has fields marked *required before close* fails with\n`400` and `internalCode: REQUIRED_FIELDS_MISSING_BEFORE_CLOSE` until those fields\nare set (they can be set in the same request).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTicketRequest"}}}},"responses":{"200":{"description":"Ticket updated. Returns the stored ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketRecord"}}}},"400":{"description":"Invalid payload, or required fields are missing before close","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/RequiredFieldsMissingError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"The ticket was created moments ago and its Slack message is not ready yet.\nSafe to retry after a short delay.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"ticketId":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}}}
```

## Reply on a ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Posts a reply in the ticket's requester thread (visible to the requester) and/or\
> responder thread (internal). For email tickets, \`requester\` sends the reply as an\
> email; the reply is always also posted in the responder thread.\
> \
> To attach files, upload each one with \[\`POST /ticket/files\`]\(#/Files/uploadFile)\
> first and pass the returned \`fileId\`s in \`attachments\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Replies"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"ReplyRequest":{"type":"object","required":["text","username","channel"],"properties":{"text":{"type":"string","minLength":1},"username":{"type":"string","minLength":1,"description":"Name shown as the author. Posted as \"Message from <username>:\" unless `impersonate` is set."},"channel":{"$ref":"#/components/schemas/ReplyChannels"},"impersonate":{"type":"boolean","description":"In the requester thread, post with `username` (and `icon_url`) as the Slack author name instead of a text prefix."},"icon_url":{"type":"string","format":"uri","description":"Avatar for the impersonated author. Requires `impersonate`."},"attachments":{"type":"array","maxItems":10,"items":{"type":"object","required":["fileId"],"properties":{"fileId":{"type":"string","description":"From `POST /ticket/files`."}}}}}},"ReplyChannels":{"type":"array","description":"`requester` — reply visible to the requester (Slack thread, or email for email tickets).\n`responder` — internal note in the responder thread.\n","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["requester","responder"]}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/reply/{ticket}":{"post":{"tags":["Replies"],"summary":"Reply on a ticket","operationId":"replyTicket","description":"**Scope:** `tickets:write`\n\nPosts a reply in the ticket's requester thread (visible to the requester) and/or\nresponder thread (internal). For email tickets, `requester` sends the reply as an\nemail; the reply is always also posted in the responder thread.\n\nTo attach files, upload each one with [`POST /ticket/files`](#/Files/uploadFile)\nfirst and pass the returned `fileId`s in `attachments`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyRequest"}}}},"responses":{"200":{"description":"Reply posted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","description":"One entry per Slack thread posted to. Informational; the contents are not guaranteed.","items":{"type":"object"}},"attachmentsUploaded":{"type":"integer"}}}}}},"400":{"description":"Invalid payload, ticket not in your workspace, or an unknown `fileId`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"An attachment's upload has expired — upload it again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"An attachment exceeds 25 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Email ticket has no responder thread to post the reply to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Upload a file for a reply

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Send the raw file bytes as the request body. The returned \`fileId\` can be used in\
> \`attachments\` on \[\`POST /ticket/reply/{ticket}\`]\(#/Replies/replyTicket) within\
> one hour. Max 25 MB per file; max 10 attachments per reply. Each file can be used\
> in one reply.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Files"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/files":{"post":{"tags":["Files"],"summary":"Upload a file for a reply","operationId":"uploadFile","description":"**Scope:** `tickets:write`\n\nSend the raw file bytes as the request body. The returned `fileId` can be used in\n`attachments` on [`POST /ticket/reply/{ticket}`](#/Replies/replyTicket) within\none hour. Max 25 MB per file; max 10 attachments per reply. Each file can be used\nin one reply.\n","parameters":[{"name":"filename","in":"query","required":false,"description":"File name shown in Slack/email. Alternatively send the `X-Filename` header. Defaults to `attachment`.","schema":{"type":"string"}},{"name":"X-Filename","in":"header","required":false,"description":"Alternative to the `filename` query parameter.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"File stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"fileId":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"The file could not be stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"File exceeds 25 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Request approval on a ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Sends an approval request to each approver in Slack. Approvers who are already on\
> the ticket are skipped.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"Approvals"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"CreateApprovalRequest":{"type":"object","required":["ticketId","approverIds","reason"],"properties":{"ticketId":{"type":"string","format":"uuid"},"approverIds":{"type":"array","minItems":1,"description":"Slack member IDs of the approvers.","items":{"type":"string"}},"reason":{"type":"string","minLength":1},"approverType":{"type":"string","enum":["basic","flexible","sequential"],"default":"basic"},"sequenceId":{"type":"string","description":"Groups approvers of one sequential approval."},"sequencePosition":{"type":"integer","minimum":0,"default":0,"description":"Order of this approver within a sequential approval."}}},"ApprovalResponse":{"type":"object","properties":{"success":{"type":"boolean"},"ticketId":{"type":"string"},"reasonId":{"type":"string"},"approversAdded":{"type":"array","items":{"type":"string"}},"approversSkipped":{"type":"array","description":"Approvers that were already on the ticket.","items":{"type":"string"}},"totalApprovers":{"type":"integer"},"approvals":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"permalink":{"type":"string","nullable":true,"description":"Link to the approval request message in Slack."}}}},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"validation":{"type":"array","description":"What failed validation. Intended for debugging; the format may change.","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/approvals":{"post":{"tags":["Approvals"],"summary":"Request approval on a ticket","operationId":"createApproval","description":"**Scope:** `tickets:write`\n\nSends an approval request to each approver in Slack. Approvers who are already on\nthe ticket are skipped.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApprovalRequest"}}}},"responses":{"200":{"description":"All approvers were already on the ticket; nothing was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalResponse"}}}},"201":{"description":"Approval requests sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalResponse"}}}},"400":{"description":"Invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Get an external ticket link

> \*\*Scope:\*\* \`tickets:read\`

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"External tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"ExternalTicket":{"type":"object","properties":{"suptaskTicketId":{"type":"string","format":"uuid","description":"The linked Suptask ticket."},"external":{"type":"object","properties":{"ticketId":{"type":"string"},"url":{"type":"string"}}},"object":{"type":"object","additionalProperties":true,"description":"The `data` sent when the link was created."}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/external/{id}":{"get":{"tags":["External tickets"],"summary":"Get an external ticket link","operationId":"getExternalTicket","description":"**Scope:** `tickets:read`","parameters":[{"name":"id","in":"path","required":true,"description":"The **external ticket ID** used when the link was created (`externalId`).","schema":{"type":"string"}}],"responses":{"200":{"description":"External ticket link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTicket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No link for this external ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Link an external ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Links a ticket in an external system to a Suptask ticket and posts a link in the\
> ticket's responder thread. An external ID can be linked once per workspace.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"External tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"schemas":{"CreateExternalTicketRequest":{"type":"object","required":["externalId","integrationType","url"],"properties":{"externalId":{"type":"string"},"integrationType":{"type":"string"},"url":{"type":"string"},"data":{"type":"object","additionalProperties":true,"description":"Any extra metadata to store with the link."}}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/external/{id}":{"post":{"tags":["External tickets"],"summary":"Link an external ticket","operationId":"createExternalTicket","description":"**Scope:** `tickets:write`\n\nLinks a ticket in an external system to a Suptask ticket and posts a link in the\nticket's responder thread. An external ID can be linked once per workspace.\n","parameters":[{"name":"id","in":"path","required":true,"description":"The **Suptask ticket UUID** to link to.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalTicketRequest"}}}},"responses":{"201":{"description":"External ticket linked","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","description":"ID of the link."}}}}}},"400":{"description":"Invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This external ID is already linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Sync a message from an external ticket

> \*\*Scope:\*\* \`tickets:write\`\
> \
> Posts a message from the external system into the linked Suptask ticket's\
> thread(s), prefixed with \*Synced message\*. Messages that are themselves synced\
> from Suptask are ignored (\`201\`, empty body) to prevent loops.<br>

```json
{"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.4.0"},"tags":[{"name":"External tickets"}],"servers":[{"url":null,"description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <your-token>`. The legacy form `Authorization: Api-Token <your-token>`\nis also accepted. Contact Suptask Support to get a token.\n"}},"parameters":{"ExternalId":{"name":"externalId","in":"path","required":true,"description":"The external ticket ID used when the link was created (`externalId`).","schema":{"type":"string"}}},"schemas":{"ReplyChannels":{"type":"array","description":"`requester` — reply visible to the requester (Slack thread, or email for email tickets).\n`responder` — internal note in the responder thread.\n","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["requester","responder"]}},"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, disabled or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token lacks the required scope, or the workspace has no API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/ticket/external/message/{externalId}":{"post":{"tags":["External tickets"],"summary":"Sync a message from an external ticket","operationId":"postExternalTicketMessage","description":"**Scope:** `tickets:write`\n\nPosts a message from the external system into the linked Suptask ticket's\nthread(s), prefixed with *Synced message*. Messages that are themselves synced\nfrom Suptask are ignored (`201`, empty body) to prevent loops.\n","parameters":[{"$ref":"#/components/parameters/ExternalId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","blocks","channel"],"properties":{"text":{"type":"string"},"blocks":{"type":"array","description":"Slack Block Kit blocks. Send `[]` for plain text.","items":{"type":"object","additionalProperties":true}},"username":{"type":"string"},"channel":{"$ref":"#/components/schemas/ReplyChannels"}}}}}},"responses":{"200":{"description":"Message posted. One entry per thread posted to; the contents are informational and not guaranteed.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"201":{"description":"Ignored — the message was synced from Suptask"},"400":{"description":"Invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"External ticket link or Suptask ticket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

***

### Request API access

The API requires a valid API token in order to authenticate to the API.

{% hint style="info" %}
Contact [Suptask Support](https://support.suptask.com/getting-started/contact-support.md) to retrieve your access token and get started with the API.
{% endhint %}

***

### How to retrieve values for the API

#### Retrieve the Form ID

Retrieve the Form ID by opening up the Form from your Inbox and edit it. From the URL you can get the Form ID which is in a UUID format:

<figure><img src="https://621243658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5JbdwXcuzsmDvD73Ccf%2Fuploads%2Fgit-blob-8b2078bac24e00194ca213d1b66b04c97fa1734f%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

#### Retrieve the field ID

Every created field in your Suptask account have a unique ID that can be retrieved from the [Manage fields](https://app.suptask.com/inboxes/fields) page by editing the field. The field ID is in a UUID format and be retried from the URL:

<figure><img src="https://621243658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5JbdwXcuzsmDvD73Ccf%2Fuploads%2Fgit-blob-04734f2b878b1e198ae2e9ef920a201ef422a92d%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

#### Retrieve the user Slack member ID

[Retrieve the Slack member ID of a user.](https://support.suptask.com/getting-started/faq.md#how-to-locate-the-member-id-of-a-slack-user-or-app)
