Using the TikitDesk API
Using the TikitDesk API
*Create and list tickets from your own scripts or another tool — for developers and technically comfortable admins.*
Authorization: Bearer <key> to POST /api/tickets (create) or GET /api/tickets (list). Everything below is one endpoint, plain JSON, no SDK required.What you'll learn
- How to generate and manage an API key
- How to create a ticket via the API
- How to list your tickets via the API
- Rate limits, error responses, and common mistakes
Prerequisites
- An Admin account (API keys are Admin-only)
- Something that can make an HTTPS request — curl, Postman, a script, a Zapier/Make webhook step, anything
Step 1 — Generate a key
Go to Settings → API Access and click Generate New Key.
Your key is shown once, in full. Copy it somewhere safe immediately — TikitDesk stores only a hash of it, the same way it stores passwords, so if you close the dialog without copying it, there is no way to retrieve it again. Generate a new one instead; the old row will still show its last 4 characters in the list so you can tell keys apart.
Treat this key like a password. Anyone who has it can create and read tickets in your workspace. If a key is ever exposed (committed to a public repo, pasted somewhere it shouldn't be), click Revoke next to it immediately — revoking takes effect instantly and cannot be undone.
Step 2 — Create a ticket
`
POST /api/tickets
Authorization: Bearer tk_your_key_here
Content-Type: application/json
{
"title": "Customer can't reset password",
"description": "They click the reset link and get a blank page.",
"priority": "High",
"client_email": "customer@example.com",
"client_name": "Jordan Lee"
}
`
Fields:
| Field | Required | Notes |
|---|---|---|
title | Yes | Up to 200 characters |
description | Yes | |
priority | No | Low, Medium, High, or Urgent. Anything else (or omitted) defaults to Low |
client_email | No | Must be a valid email address or it's ignored |
client_name | No | Up to 150 characters |
department | No | Must match an existing department name exactly. If omitted or not recognized, your first configured department is used instead |
category | No | Same rule as department |
type | No | Same rule as department |
project | No | Same rule as department |
A form-encoded POST body works exactly the same as JSON — use whichever your tool makes easier.
Response (success, HTTP 200):
`json
{ "status": "success", "ticket_no": 142, "message": "Ticket #T-142 created." }
`
New tickets always start in the Open status and Unassigned, exactly like a ticket created by a teammate in the app — pick them up from the board like any other.
Step 3 — List tickets
`
GET /api/tickets?limit=25&offset=0
Authorization: Bearer tk_your_key_here
`
Query parameters (all optional):
| Parameter | Default | Notes |
|---|---|---|
limit | 25 | Maximum 100 |
offset | 0 | For paging through results |
status | — | Exact status name, e.g. Open or Close |
Response (HTTP 200):
`json
{
"status": "success",
"count": 2,
"tickets": [
{
"ticket_no": 142,
"title": "Customer can't reset password",
"description": "They click the reset link and get a blank page.",
"status": "Open",
"department": "Support",
"assigned_to": "Unassigned",
"priority": "High",
"client_email": "customer@example.com",
"client_name": "Jordan Lee",
"created_at": "2026-08-20 11:42:00",
"resolved_at": null
}
]
}
`
Rate limits
60 requests per minute per key. Going over it returns HTTP 429 with a plain error message — back off and retry after a few seconds. If your integration legitimately needs more (e.g. a bulk import), space requests out rather than firing them all at once.
Errors
Every error comes back as JSON with a message you can log or show directly:
| HTTP code | Meaning |
|---|---|
| 401 | Missing or invalid key — check the Authorization: Bearer header is present and the key hasn't been revoked |
| 403 | Your plan's monthly ticket limit has been reached |
| 422 | title or description was missing or empty |
| 429 | Rate limit exceeded (see above) |
| 405 | Wrong HTTP method — this endpoint only accepts GET and POST |
| 500 | Something went wrong on our end — safe to retry once; contact support if it keeps happening |
Good to know
- Works from browser JS too: this endpoint sends the CORS headers needed to call it directly from client-side JavaScript (a
fetch()in your own website, a no-code tool's custom-code step, this article's own examples) — not just from a server or curl. - One endpoint today:
/api/tickets. It does not yet cover comments, attachments, or status updates — only creating and listing tickets. - Your data only: a key can only ever see and create tickets for your own company. There's no way to access another workspace's data with a key, no matter what you pass in.
- No SDKs yet: it's plain HTTPS + JSON, so any language's standard HTTP client works. A Node/Python example:
`bash
curl -X POST https://tikitdesk.com/api/tickets \
-H "Authorization: Bearer tk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"title":"Test ticket","description":"Just testing the API"}'
`