> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minidesk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get a key, open a ticket, and read the reply. Around five minutes.

You will end this guide with a ticket opened from the command line, visible in
your inbox.

## 1. Get an API key

<Steps>
  <Step title="Open your workspace settings">
    In the dashboard, head to **Settings → API**. Workspace owner access is
    required.
  </Step>

  <Step title="Create a credential">
    Label it with where it will run, something like `billing-service` or
    `staging`. That label is what you check later when deciding if a revoke is
    safe.
  </Step>

  <Step title="Copy the token">
    It begins with `mdsk_api_` and appears **only once**. We keep a hash, not
    the token itself, so it cannot be shown again. Lost it? Revoke and create a
    fresh one.
  </Step>
</Steps>

<Warning>
  Treat this token like a password. Every conversation in the workspace is
  readable through it, and replies can be sent from it. Keep it on a server,
  never inside a browser bundle or a mobile app.
</Warning>

## 2. Open a ticket

```bash theme={null}
curl -X POST https://api.minidesk.ai/v1/tickets \
  -H "Authorization: Bearer $MINIDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Clicking export does nothing.",
    "requester": { "email": "sam@customer.com", "name": "Sam" }
  }'
```

Here is the ticket you get back:

```json theme={null}
{
  "id": "0195e2c1-...",
  "reference": "ACME-1042",
  "status": "new",
  "priority": "normal",
  "category": "billing",
  "source": "api",
  "language": "en",
  "requester": {
    "id": "0195e2c0-...",
    "email": "sam@customer.com",
    "name": "Sam",
    "is_verified": false
  },
  "created_at": "2026-08-28T10:31:00Z",
  "updated_at": "2026-08-28T10:31:00Z"
}
```

A few things were filled in that you did not send. Triage added `priority` and
`category` since you left them blank, and `language` was detected from the
message body. Values you set yourself are preserved as-is.

Notice there is no subject field. That is intentional. The first message is
the ticket's description, so there is nothing for you to invent.

### Verified and unverified requesters

`is_verified` is `false` here because an email address alone does not prove
identity.

If your own system has already authenticated this person, pass that along with
`external_id`:

```json theme={null}
{
  "body": "Clicking export does nothing.",
  "requester": {
    "email": "sam@customer.com",
    "name": "Sam",
    "external_id": "usr_913"
  }
}
```

Including `external_id` is your assertion that **you** authenticated them. The
requester is then stored as verified, and your agents can trust that.

## 3. Read the conversation

```bash theme={null}
curl https://api.minidesk.ai/v1/tickets/0195e2c1-... \
  -H "Authorization: Bearer $MINIDESK_TOKEN"
```

This returns the ticket along with its public messages. Internal notes are
never part of this response, regardless of parameters.

## 4. Reply

```bash theme={null}
curl -X POST https://api.minidesk.ai/v1/tickets/0195e2c1-.../messages \
  -H "Authorization: Bearer $MINIDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "We shipped a fix. Please try again." }'
```

Sam receives that on the channel the ticket came in on. To leave a note for
your team instead, add `"visibility": "internal"` and nobody outside the
workspace hears about it.

## 5. Close it

```bash theme={null}
curl -X PATCH https://api.minidesk.ai/v1/tickets/0195e2c1-... \
  -H "Authorization: Bearer $MINIDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'
```

A reply from Sam on a resolved ticket reopens it automatically. That is the one
status transition the system performs without a person.

## Where to go next

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Every endpoint, each with a playground on the page.
  </Card>

  <Card title="Idempotency" icon="rotate" href="/guides/idempotency">
    Read this one before putting ticket creation behind a retry.
  </Card>

  <Card title="Set up a channel" icon="inbox" href="/channels/overview">
    Most conversations should arrive on their own, not through the API.
  </Card>

  <Card title="Connect an AI agent" icon="robot" href="/mcp/overview">
    Point Claude or ChatGPT at your queue.
  </Card>
</CardGroup>