# TuraDesk Quick Start

**Add help desk and support ticketing to your app in 5 minutes.**

---

## Step 1: Get Your API Key (1 minute)

TuraDesk uses TuraLogin API keys.

1. Go to https://www.turalogin.com
2. Sign up and create an app
3. Copy your test API key: `tl_test_xxxxxxxxxxxxxxxx`

Dashboard: https://www.turalogin.com/dashboard/keys

---

## Step 2: Create a Ticket (1 minute)

```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",
  "status": "open",
  "email": "customer@example.com",
  "createdAt": "2026-02-17T10:00:00Z"
}
```

Save the `id` — you'll need it for the next steps.

---

## Step 3: List Tickets (1 minute)

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

**Optional filters:**
- `status` — `open`, `pending`, `resolved`, `closed`
- `priority` — `low`, `medium`, `high`, `urgent`
- `tag` — filter by tag
- `assignee` — filter by assignee
- `limit` — max results (default 20, max 100)
- `cursor` — for pagination

---

## Step 4: Get Ticket with Comments (1 minute)

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

Replace `tkt_abc123xyz` with your ticket ID from Step 2.

---

## Step 5: Add a Comment (1 minute)

```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
  }'
```

- `internal: true` — only visible to agents
- `internal: false` — visible to customer (default)

---

## Next Steps

### Update a Ticket

```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"
  }'
```

### Close a Ticket

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

### Get Stats

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

---

## Add to Your App

**Environment variable:**
```bash
TURADESK_API_KEY=tl_test_your_key_here
```

**Next.js example:**
```typescript
// app/api/support/tickets/route.ts
export async function POST(request: Request) {
  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),
  });
  
  return Response.json(await res.json());
}
```

**Important:** Never expose your API key to the frontend. Always proxy TuraDesk calls through your backend.

---

## Full Documentation

- 📖 [SKILL.md](https://www.turadesk.com/SKILL.md) — Complete API reference
- 📖 [AGENTS.md](https://www.turadesk.com/AGENTS.md) — AI agent integration guide
- 📖 [API.md](https://www.turadesk.com/API.md) — Detailed endpoint docs

---

**Done!** You now have API-first support ticketing.