API & extension points

REST API

Everything the UI can do is available at /api/v1/*, authenticated with Authorization: Bearer <api-key> — tickets, board moves, messages and drafts, comments, contacts, statuses, tags, custom fields, settings, email snippets, and users.

The full surface is described by the OpenAPI spec in the repo at docs/openapi.yaml:

• pnpm openapi:generate — regenerate the spec
• pnpm openapi:check — verify it matches the routes

Browse the generated API reference for interactive endpoint docs grouped by resource.

In the examples below, set your instance URL once and reuse it:

export TICQEX_INSTANCE_URL="https://your-instance.example.com"

MCP server

The MCP endpoint at /api/mcp exposes tools mirroring the REST mutations. Parity between the two is enforced by a test suite, so anything you can automate over HTTP you can also do from an MCP-connected agent. See Connect an agent.

API keys

Create API keys in Settings → API & MCP. Keys are shown once, start with tq_live_, and work across REST, MCP, the CLI, and the TypeScript client.

For direct HTTP calls:

curl "$TICQEX_INSTANCE_URL/api/v1/users/me" \
  -H "Authorization: Bearer tq_live_..."

CLI

Use the published CLI for shell-based agents, local scripts, release checks, and demos:

pnpm dlx @ticqex/cli --help
pnpm dlx @ticqex/cli auth login --instance "$TICQEX_INSTANCE_URL"
pnpm dlx @ticqex/cli tickets list --page 1 --per-page 20
pnpm dlx @ticqex/cli board get

auth login prompts for the API key and stores it under your user config directory. You can also pass credentials per command:

pnpm dlx @ticqex/cli tickets list \
  --instance "$TICQEX_INSTANCE_URL" \
  --api-key tq_live_...

The CLI also exposes every MCP-parity operation by catalog name:

pnpm dlx @ticqex/cli call ticqex_get_ticket --input '{"id":"<ticket-id>"}'

Package: @ticqex/cli

TypeScript client

Install the API client when building an integration, app, worker, or agent runtime:

pnpm add @ticqex/api-client

import { TicqexClient } from "@ticqex/api-client";

const client = new TicqexClient({
  baseUrl: process.env.TICQEX_INSTANCE_URL!,
  apiKey: process.env.TICQEX_API_KEY!,
});

const me = await client.get("/users/me");
const tickets = await client.get("/tickets", { page: 1, per_page: 25 });
const created = await client.post("/tickets", {
  subject: "Login issue",
  contact_email: "user@example.com",
});

Paths are relative to /api/v1; the client adds that prefix and normalizes the base URL for you. API errors throw TicqexApiError with status, code, and message.

Package: @ticqex/api-client

Package surface

Ticqex publishes @ticqex/cli and @ticqex/api-client on npm.

@ticqex/api-spec is intentionally internal. The CLI bundles the operation catalog it needs, so consumers do not need to install the spec package.

Building integrations without forking

If you just need to get tickets in or out — a web form, a Slack workflow, a Zapier-style automation — you usually don't need a new channel at all: create tickets via the REST API (origin api). Build a full channel only when you need threaded two-way conversations with channel-specific behavior — see Adding a channel.