# LitosFlow API

> Programmatic access to your organization's tickets, comments, and boards.

A versioned REST API for building integrations against your tickets, comments, and boards. Every endpoint returns JSON, is authenticated with a personal access token, and acts as the member that token belongs to — in one organization only. A token's scopes can never exceed what its member's role already allows, so restricting a role restricts every token it issued.

- Base URL: `https://dev-api.litosflow.com/api/v1`
- Auth: `Authorization: Bearer <token>` (personal access token, prefix `ltf_`)
- OpenAPI: `https://dev-api.litosflow.com/api/v1/openapi.json`
- Rate limit: 60 requests/minute per token (429 returns a `Retry-After` header)

## Scopes

A token carries an explicit set of scopes, drawn from the same permission catalog as workspace roles. A request succeeds only when the token has the endpoint's scope AND the member's role still grants that permission.

- `view_all_tickets` — Read every ticket, board, status, and comment in the organization.
- `view_own_tickets` — Read only tickets the member reported or is assigned to (and their comments).
- `create_tickets` — Create tickets and author comments.
- `edit_any_ticket` — Update any ticket in the organization.
- `edit_assigned_tickets` — Update only tickets assigned to the member.

## Endpoints

### Identity

- `GET /me` — Identify the token (scope: no scope required)
  Returns the member, organization, and scopes this token operates as. Handy for verifying a credential.

### Reference

- `GET /boards` — List boards (scope: `view_all_tickets` or `view_own_tickets`)
  Boards in the organization, with their ticket prefix and count.
- `GET /statuses` — List statuses (scope: `view_all_tickets` or `view_own_tickets`)
  Board columns (statuses) across the organization, including which column completes a ticket. Use these ids when creating or moving tickets.

### Tickets

- `POST /tickets` — Create a ticket (scope: `create_tickets`)
  Creates a ticket. The reporter is always the token's member — it is never taken from the body. `board` and `status` ids come from `GET /boards` and `GET /statuses`; the status must be a column of the chosen board.
- `GET /tickets/{ticket}` — Get a ticket (scope: `view_all_tickets` or `view_own_tickets`)
  A single ticket with its comments, tags, checklist, links, and attachment metadata.
- `GET /tickets` — List tickets (scope: `view_all_tickets` or `view_own_tickets`)
  Paginated list of tickets. Supports search, board/status/priority/assignee/tag filters, date ranges, and sorting. A `view_own_tickets`-only token sees only tickets its member reported or is assigned to.
- `PATCH /tickets/{ticket}` — Update a ticket (scope: `edit_any_ticket` or `edit_assigned_tickets`)
  Updates any subset of a ticket's fields. With only `edit_assigned_tickets`, the ticket must be assigned to the token's member. Omitted fields are left unchanged.

### Comments

- `POST /tickets/{ticket}/comments` — Add a comment (scope: `create_tickets`)
  Adds a comment authored by the token's member.
- `DELETE /tickets/{ticket}/comments/{comment}` — Delete a comment (scope: `create_tickets`)
  Deletes one of the token member's own comments.
- `GET /tickets/{ticket}/comments` — List comments (scope: `view_all_tickets` or `view_own_tickets`)
  Comments on a ticket, oldest first.
- `PATCH /tickets/{ticket}/comments/{comment}` — Edit a comment (scope: `create_tickets`)
  Edits one of the token member's own comments. Editing another member's comment is rejected.

## Errors

Errors are JSON with a `message`. `401` missing/expired/revoked token, `403` missing scope, `404` outside your organization or visibility, `422` validation failure (`errors` maps each field to its messages), `429` rate limited.