> ## 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.

# Introduction

> The versioned REST API for reading and working tickets.

```
https://api.minidesk.ai/v1
```

Six endpoints. Create a ticket, list and read tickets, update one, and read or
post messages.

<Card title="Authentication" icon="key" href="/guides/authentication">
  Every request needs `Authorization: Bearer mdsk_api_...`, from
  **Settings → API**.
</Card>

## Conventions

**JSON in, JSON out.** Send `Content-Type: application/json` on anything
with a body.

**Timestamps are ISO 8601 in UTC**, always.

**Ids are UUIDs.** `reference` (`ACME-1042`) is the human-facing label, the one
you show people. `id` is what you pass to the API.

**Every response carries `X-Request-Id`.** Log it, and include it when you
report a problem.

## Versioning

The version lives in the path. Additive changes ship in place, so your
integration should ignore fields it does not recognise rather than failing on
them. A breaking change gets a new version.

## The ticket lifecycle

```
new → open → pending → resolved → closed
```

`resolved` and `closed` can both go back to `open`. Anything else the state
machine does not allow returns `422 invalid_transition`.

A requester replying to a resolved ticket reopens it. That is the one
transition that happens without a person.

## Public and internal messages

A message is `public` or `internal`, and the difference is who can see it.

A **public** message reaches the requester on the channel the ticket arrived
on. An **internal** note notifies nobody outside the workspace.

Internal notes are never returned by this API, on any endpoint, with any
parameter. If you need them, they are in the dashboard.

## What this API does not expose

Drafts, the AI audit log, automation settings, billing, and knowledge sources
are all dashboard-only for now.

Reading the audit log is the most likely early addition, since compliance teams
tend to ask for it.

## Before you build

<CardGroup cols={2}>
  <Card title="Idempotency" icon="rotate" href="/guides/idempotency">
    Read this before putting ticket creation behind a retry.
  </Card>

  <Card title="Pagination" icon="list" href="/guides/pagination">
    Cursors, not page numbers, and why.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/guides/errors">
    One envelope, a fixed set of codes, and which are worth retrying.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/guides/rate-limits">
    600 a minute per credential.
  </Card>
</CardGroup>

## The dashboard's own API is not this one

The dashboard talks to a different, unversioned surface using a signed-in
agent's session. It is internal and changes without notice.

Everything documented here is the stable one. If you find an endpoint that is
not in this reference, it is not a contract and it will move.