---
name: turadesk
version: 1.0.0
description: Help desk and support ticketing API. Create tickets, assign agents, track status, add comments. Part of Tura Cloud.
homepage: https://www.turadesk.com
metadata: {"category":"support","api_base":"https://www.turadesk.com/api/v1"}
---

# TuraDesk

**API-first help desk and support ticketing service.**

TuraDesk lets you create tickets, assign agents, track status, add comments. Auth uses TuraLogin API keys (Bearer token). Part of Tura Cloud.

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://www.turadesk.com/SKILL.md` |
| **AGENTS.md** | `https://www.turadesk.com/AGENTS.md` |
| **API.md** | `https://www.turadesk.com/API.md` |
| **QUICKSTART.md** | `https://www.turadesk.com/QUICKSTART.md` |
| **skill.json** (metadata) | `https://www.turadesk.com/skill.json` |

**Install locally:**
```bash
mkdir -p ~/.turadesk
curl -s https://www.turadesk.com/SKILL.md > ~/.turadesk/SKILL.md
curl -s https://www.turadesk.com/AGENTS.md > ~/.turadesk/AGENTS.md
curl -s https://www.turadesk.com/API.md > ~/.turadesk/API.md
curl -s https://www.turadesk.com/QUICKSTART.md > ~/.turadesk/QUICKSTART.md
```

**Base URL:** `https://www.turadesk.com/api/v1`

🔒 **Authentication:** All endpoints require `Authorization: Bearer <API_KEY>`. API keys from [turalogin.com/dashboard/keys](https://www.turalogin.com/dashboard/keys).

---

## Overview

TuraDesk is an API-first help desk. You implement:

✅ **Ticket creation** — Create tickets with subject, body, priority, email, tags  
✅ **Ticket management** — List, get, update, close tickets  
✅ **Comments** — Add public or internal comments  
✅ **Agent assignment** — Assign tickets to support agents  
✅ **Stats** — Ticket counts by status, average resolution time  

You handle:
- Your support UI (dashboard, forms, views)
- Agent management (if needed)
- Email notifications to customers (optional — TuraDesk can notify or you can)
- Custom workflows and automation

---

## Quick Start

### 1. Get Your API Key

TuraDesk uses TuraLogin API keys. Get one at:
- https://www.turalogin.com/dashboard/keys

Use the same API key format: `tl_test_xxx` (development) or `tl_live_xxx` (production).

### 2. Create a Ticket

```bash
curl -X POST https://www.turadesk.com/api/v1/desk/tickets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Login issue",
    "body": "User cannot sign in after password reset",
    "priority": "high",
    "email": "customer@example.com",
    "tags": ["login", "urgent"]
  }'
```

**Response:**
```json
{
  "id": "tkt_abc123xyz",
  "subject": "Login issue",
  "body": "User cannot sign in after password reset",
  "priority": "high",
  "status": "open",
  "email": "customer@example.com",
  "tags": ["login", "urgent"],
  "assignee": null,
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}
```

### 3. List Tickets

```bash
curl "https://www.turadesk.com/api/v1/desk/tickets?status=open&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 4. Add a Comment

```bash
curl -X POST https://www.turadesk.com/api/v1/desk/tickets/tkt_abc123xyz/comments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Investigating the issue. Will update shortly.",
    "internal": false
  }'
```

---

## Full API Reference

### Authentication

All requests require:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

API keys come from TuraLogin: https://www.turalogin.com/dashboard/keys

---

### POST /api/v1/desk/tickets

Create a new support ticket.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subject` | string | Yes | Ticket subject (max 256 chars) |
| `body` | string | Yes | Ticket body/description |
| `priority` | string | No | `low`, `medium`, `high`, `urgent` (default: `medium`) |
| `email` | string | Yes | Requester email address |
| `tags` | string[] | No | Array of tag strings |

**Example:**
```bash
curl -X POST https://www.turadesk.com/api/v1/desk/tickets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Billing question",
    "body": "When will my invoice be sent?",
    "priority": "medium",
    "email": "user@example.com",
    "tags": ["billing", "invoice"]
  }'
```

**Success Response (201):**
```json
{
  "id": "tkt_abc123xyz",
  "subject": "Billing question",
  "body": "When will my invoice be sent?",
  "priority": "medium",
  "status": "open",
  "email": "user@example.com",
  "tags": ["billing", "invoice"],
  "assignee": null,
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}
```

---

### GET /api/v1/desk/tickets

List tickets with optional filters and pagination.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter: `open`, `pending`, `resolved`, `closed` |
| `assignee` | string | Filter by assignee ID or email |
| `priority` | string | Filter: `low`, `medium`, `high`, `urgent` |
| `tag` | string | Filter by tag (exact match) |
| `limit` | number | Max results (default: 20, max: 100) |
| `cursor` | string | Pagination cursor from previous response |

**Example:**
```bash
curl "https://www.turadesk.com/api/v1/desk/tickets?status=open&priority=high&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "tickets": [
    {
      "id": "tkt_abc123",
      "subject": "Login issue",
      "priority": "high",
      "status": "open",
      "email": "user@example.com",
      "tags": ["login"],
      "assignee": null,
      "createdAt": "2026-02-17T10:00:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6InRrdF9hYmMxMjMifQ==",
  "hasMore": true
}
```

---

### GET /api/v1/desk/tickets/:id

Get a single ticket with its comments.

**Example:**
```bash
curl https://www.turadesk.com/api/v1/desk/tickets/tkt_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "id": "tkt_abc123xyz",
  "subject": "Login issue",
  "body": "User cannot sign in",
  "priority": "high",
  "status": "open",
  "email": "user@example.com",
  "tags": ["login", "urgent"],
  "assignee": null,
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z",
  "comments": [
    {
      "id": "cmt_xyz789",
      "body": "Investigating now.",
      "internal": false,
      "author": "agent@support.com",
      "createdAt": "2026-02-17T10:15:00Z"
    }
  ]
}
```

---

### PATCH /api/v1/desk/tickets/:id

Update a ticket (status, assignee, priority, tags).

**Request Body (all optional):**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | `open`, `pending`, `resolved`, `closed` |
| `assignee` | string | Assignee ID or email |
| `priority` | string | `low`, `medium`, `high`, `urgent` |
| `tags` | string[] | Replace tags with new array |

**Example:**
```bash
curl -X PATCH https://www.turadesk.com/api/v1/desk/tickets/tkt_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "pending",
    "assignee": "agent@support.com",
    "priority": "high"
  }'
```

**Success Response (200):** Returns updated ticket object.

---

### DELETE /api/v1/desk/tickets/:id

Close/delete a ticket.

**Example:**
```bash
curl -X DELETE https://www.turadesk.com/api/v1/desk/tickets/tkt_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "success": true,
  "message": "Ticket closed"
}
```

---

### POST /api/v1/desk/tickets/:id/comments

Add a comment to a ticket.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `body` | string | Yes | Comment text |
| `internal` | boolean | No | If true, only visible to agents (default: false) |

**Example:**
```bash
curl -X POST https://www.turadesk.com/api/v1/desk/tickets/tkt_abc123xyz/comments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Issue resolved. User can now log in.",
    "internal": false
  }'
```

**Success Response (201):**
```json
{
  "id": "cmt_xyz789",
  "body": "Issue resolved. User can now log in.",
  "internal": false,
  "author": "agent@support.com",
  "createdAt": "2026-02-17T10:30:00Z"
}
```

---

### GET /api/v1/desk/stats

Get ticket statistics.

**Example:**
```bash
curl https://www.turadesk.com/api/v1/desk/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "byStatus": {
    "open": 12,
    "pending": 5,
    "resolved": 48,
    "closed": 120
  },
  "avgResolutionTimeHours": 4.2,
  "totalTickets": 185
}
```

---

## Framework Examples

### Next.js (App Router)

```typescript
// app/api/support/tickets/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const body = await request.json();
  
  const res = await fetch('https://www.turadesk.com/api/v1/desk/tickets', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TURADESK_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  
  const data = await res.json();
  return NextResponse.json(data);
}

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const query = new URLSearchParams(searchParams).toString();
  
  const res = await fetch(`https://www.turadesk.com/api/v1/desk/tickets?${query}`, {
    headers: {
      'Authorization': `Bearer ${process.env.TURADESK_API_KEY}`,
    },
  });
  
  const data = await res.json();
  return NextResponse.json(data);
}
```

### Express.js

```javascript
const express = require('express');
const app = express();

app.post('/api/tickets', async (req, res) => {
  const response = await fetch('https://www.turadesk.com/api/v1/desk/tickets', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TURADESK_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(req.body),
  });
  
  const data = await response.json();
  res.json(data);
});

app.get('/api/tickets', async (req, res) => {
  const query = new URLSearchParams(req.query).toString();
  const response = await fetch(
    `https://www.turadesk.com/api/v1/desk/tickets?${query}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TURADESK_API_KEY}`,
      },
    }
  );
  
  const data = await response.json();
  res.json(data);
});
```

### Python (FastAPI)

```python
from fastapi import FastAPI, HTTPException
import httpx
import os

app = FastAPI()
TURADESK_API_KEY = os.getenv("TURADESK_API_KEY")

@app.post("/api/tickets")
async def create_ticket(subject: str, body: str, email: str, priority: str = "medium", tags: list = None):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://www.turadesk.com/api/v1/desk/tickets",
            headers={
                "Authorization": f"Bearer {TURADESK_API_KEY}",
                "Content-Type": "application/json",
            },
            json={
                "subject": subject,
                "body": body,
                "email": email,
                "priority": priority,
                "tags": tags or [],
            },
        )
        return response.json()

@app.get("/api/tickets")
async def list_tickets(status: str = None, limit: int = 20):
    params = {"limit": limit}
    if status:
        params["status"] = status
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://www.turadesk.com/api/v1/desk/tickets",
            headers={"Authorization": f"Bearer {TURADESK_API_KEY}"},
            params=params,
        )
        return response.json()
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func createTicket(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Subject  string   `json:"subject"`
        Body     string   `json:"body"`
        Email    string   `json:"email"`
        Priority string   `json:"priority"`
        Tags     []string `json:"tags"`
    }
    json.NewDecoder(r.Body).Decode(&req)
    
    body, _ := json.Marshal(req)
    httpReq, _ := http.NewRequest(
        "POST",
        "https://www.turadesk.com/api/v1/desk/tickets",
        bytes.NewBuffer(body),
    )
    httpReq.Header.Set("Authorization", "Bearer "+os.Getenv("TURADESK_API_KEY"))
    httpReq.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(httpReq)
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}
```

---

## Security Model

- **API keys** — Use TuraLogin API keys. Never expose keys in client-side code.
- **Environment variables** — Store `TURADESK_API_KEY` in env (or reuse `TURALOGIN_API_KEY` if same app).
- **HTTPS only** — All API calls must use HTTPS in production.

---

## Rate Limits

| Scope | Limit | Window |
|-------|-------|--------|
| API requests | 100 | Per minute |
| Ticket creation | 50 | Per minute |

When exceeded, you receive `429 Too Many Requests` with `Retry-After` header.

---

## Error Codes

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `subject is required` | Missing subject |
| 400 | `body is required` | Missing body |
| 400 | `email is required` | Missing email |
| 400 | `Invalid email address` | Malformed email |
| 400 | `Invalid priority` | Must be low, medium, high, or urgent |
| 401 | `Unauthorized` | Missing or invalid API key |
| 404 | `Ticket not found` | Invalid ticket ID |
| 429 | `Too many requests` | Rate limit exceeded |
| 500 | `Internal server error` | Server-side error |

---

## Support & Resources

- 🌐 Website: https://www.turadesk.com
- 📖 [AGENTS.md](https://www.turadesk.com/AGENTS.md) — AI agent integration guide
- 📖 [API.md](https://www.turadesk.com/API.md) — Complete API reference
- 📖 [QUICKSTART.md](https://www.turadesk.com/QUICKSTART.md) — 5-minute integration
- 🔑 API Keys: https://www.turalogin.com/dashboard/keys

---

**Built for developers who want support ticketing without the complexity.**