API

Authorization: Bearer $TIKKETTY_TOKEN

read -rs TIKKETTY_TOKEN
export TIKKETTY_TOKEN

{
  "items": [
    "…"
  ],
  "nextCursor": "41"
}

curl "https://tikketty.com/api/issues?limit=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $TIKKETTY_TOKEN"

{
  "items": [
    {
      "id": "7a0c5e3b-1f8d-4b26-9e4a-0d2c6b8f1e53",
      "number": 41,
      "projectId": "7fe8130d-f5e0-45d1-9852-c26986e665eb",
      "type": "task",
      "parentId": null,
      "sprintId": null,
      "rank": 43008,
      "progress": null,
      "title": "Checkout button overlaps the footer on mobile",
      "description": "On iPhone 15 the Pay now button sits on top of the footer links.",
      "status": "inbox",
      "priority": "important",
      "assigneeIds": [],
      "tags": [
        "checkout",
        "mobile"
      ],
      "startDate": null,
      "dueDate": null,
      "storyPoints": null,
      "visibility": "shared",
      "reporterId": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
      "url": "https://www.example.com/checkout",
      "selector": "",
      "position": null,
      "environment": {},
      "archived": false,
      "mergedInto": null,
      "assetId": null,
      "assetVersionId": null,
      "assetPage": null,
      "createdAt": "2026-11-02T15:04:05.120Z",
      "updatedAt": "2026-11-02T15:04:05.120Z"
    }
  ],
  "nextCursor": null
}

{
  "error": "title: Too small: expected string to have >=1 characters"
}

curl -X PATCH https://tikketty.com/api/issues/ISSUE_ID/comments/COMMENT_ID \
  -H "Authorization: Bearer $TIKKETTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Fixed in the next deploy, Friday." }'

{
  "id": "5e2d8c41-7a9b-4f03-b6e1-2c9d0f4a8b73",
  "issueId": "c3a1f0e2-5b7d-4e9a-8f21-6d4b9c0e7a15",
  "userId": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
  "body": "Fixed in the next deploy, Friday.",
  "internal": false,
  "createdAt": "2026-11-02T15:20:41.008Z",
  "editedAt": "2026-11-02T15:31:07.219Z",
  "author": {
    "id": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
    "name": "Alex Morgan",
    "email": "alex@example.com"
  }
}

{
  "id": "0b7e4f2a-91c3-4d58-a6e0-3f8b2d1c9e47",
  "issueId": "c3a1f0e2-5b7d-4e9a-8f21-6d4b9c0e7a15",
  "userId": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
  "action": "updated",
  "detail": "status, assigneeIds",
  "createdAt": "2026-11-02T15:12:09.554Z",
  "author": {
    "id": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
    "name": "Alex Morgan",
    "email": "alex@example.com"
  }
}

{
  "id": "49282567-1d17-4c0c-8cb0-b5af0bd50e9e",
  "name": "Sam Rivera",
  "email": "sam@example.com",
  "role": "member"
}

{
  "id": "9d1f3b6e-2a4c-4e87-b0d5-7c6a8e2f1b39",
  "issueId": "c3a1f0e2-5b7d-4e9a-8f21-6d4b9c0e7a15",
  "title": "Comment: Checkout button overlaps the footer on mobile",
  "kind": "comment",
  "read": false,
  "createdAt": "2026-11-02T15:20:41.008Z"
}

curl https://tikketty.com/api/issues/ISSUE_ID/attachments \
  -H "Authorization: Bearer $TIKKETTY_TOKEN" \
  -F "file=@screenshot.png"

{
  "id": "e41b7c9a-3d62-4f8e-a5b0-1c7d9e2f6a84",
  "issueId": "c3a1f0e2-5b7d-4e9a-8f21-6d4b9c0e7a15",
  "name": "screenshot.png",
  "size": 48213,
  "type": "image/png",
  "internal": false,
  "createdAt": "2026-11-02T15:25:13.771Z"
}

curl -L -o screenshot.png https://tikketty.com/api/attachments/ATTACHMENT_ID/download \
  -H "Authorization: Bearer $TIKKETTY_TOKEN"

curl https://tikketty.com/api/webhooks \
  -H "Authorization: Bearer $TIKKETTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "url": "https://example.com/webhooks/tikketty",
    "events": ["issue.created", "issue.updated", "issue.commented"]
  }'

{
  "id": "a8c2e6f0-4b1d-4e93-9f7a-5d3c1b8e0f26",
  "projectId": "7fe8130d-f5e0-45d1-9852-c26986e665eb",
  "url": "https://example.com/webhooks/tikketty",
  "events": [
    "issue.created",
    "issue.updated",
    "issue.commented"
  ],
  "createdAt": "2026-11-02T15:30:00.412Z",
  "secret": "4f7d1c9e2b8a6f3d0e5c7b9a1d4f6e8c2b0a9d7f5e3c1b8a6d4f2e0c9b7a5d3f"
}

{
  "eventId": "0b7e4f2a-91c3-4d58-a6e0-3f8b2d1c9e47",
  "event": "issue.updated",
  "projectId": "7fe8130d-f5e0-45d1-9852-c26986e665eb",
  "issueId": "c3a1f0e2-5b7d-4e9a-8f21-6d4b9c0e7a15",
  "actorId": "b804b2c7-1593-4940-9ee9-7511a76f6b17",
  "createdAt": "2026-11-02T15:12:09.554Z",
  "deliveryId": "3f9c2a7d0b6e4c1a9e8f7d6c5b4a3921"
}

import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const secret = process.env.TIKKETTY_WEBHOOK_SECRET;

function verify(rawBody, headers) {
  const timestamp = String(headers["tikketty-timestamp"] ?? "");
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex"));
  const received = Buffer.from(String(headers["tikketty-signature"] ?? ""));
  return received.length === expected.length && timingSafeEqual(received, expected);
}

createServer((req, res) => {
  const chunks = [];
  req.on("data", chunk => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks).toString("utf8");
    if (req.method !== "POST" || !verify(rawBody, req.headers)) return res.writeHead(401).end();
    const event = JSON.parse(rawBody);
    if (event.deliveryId !== req.headers["tikketty-delivery"]) return res.writeHead(400).end();
    console.log(event.event, event.issueId);
    res.writeHead(204).end();
  });
}).listen(process.env.PORT || 3000);

curl -N https://tikketty.com/api/events \
  -H "Authorization: Bearer $TIKKETTY_TOKEN"

retry: 2000

id: 118
event: ready
data: {"revision":118}

id: 119
event: change
data: {"revision":119}

TIKKETTY_URL=https://tikketty.com node api-client.mjs issues 25
TIKKETTY_URL=https://tikketty.com node api-client.mjs create PROJECT_ID '{"title":"Review the header"}'
TIKKETTY_URL=https://tikketty.com node api-client.mjs update ISSUE_ID '{"status":"todo","priority":"important"}'
TIKKETTY_URL=https://tikketty.com node api-client.mjs comment ISSUE_ID 'Reproduced on staging.'

#!/usr/bin/env node
// Dependency-free CLI example; mutation requests are never retried.
const usage = 'Usage: api-client.mjs [issues [limit] | create PROJECT_ID JSON | update ISSUE_ID JSON | comment ISSUE_ID BODY]';
const token = process.env.TIKKETTY_TOKEN || '';
const print = (stream, value) => stream.write((token ? value.replaceAll(token, '[redacted]') : value) + '\n');

try {
  const origin = process.env.TIKKETTY_URL || 'http://127.0.0.1:3001';
  if (!/^https?:\/\//.test(origin) || /[\\\s?#]/.test(origin)) throw new Error('TIKKETTY_URL must be an HTTPS origin or loopback HTTP origin.');
  let base;
  try { base = new URL(origin); } catch { throw new Error('Invalid TIKKETTY_URL.'); }
  if (base.username || base.password || base.pathname !== '/' || !base.hostname || (base.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(base.hostname))) {
    throw new Error('TIKKETTY_URL must be an HTTPS origin or loopback HTTP origin.');
  }
  if (!token || token.length > 8192 || /[^\x21-\x7e]/.test(token)) throw new Error('Set TIKKETTY_TOKEN privately to a valid API token.');
  const [command = 'issues', ...args] = process.argv.slice(2);
  const fields = new Set(['title', 'description', 'status', 'priority', 'dueDate']);
  const object = text => {
    let value;
    try { value = JSON.parse(text); } catch { throw new Error('JSON must be an object with supported issue fields.'); }
    if (!value || Array.isArray(value) || typeof value !== 'object' || !Object.keys(value).length || Object.keys(value).some(key => !fields.has(key))) throw new Error('JSON must be an object with supported issue fields.');
    return value;
  };
  const identifier = value => {
    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value || '')) throw new Error('Use the project or issue UUID from the API.');
    return value;
  };
  let path, method = 'GET', body;
  if (command === 'issues' && args.length <= 1) {
    const limit = args[0] || '50';
    if (!/^[1-9]\d?$|^100$/.test(limit)) throw new Error('Page limit must be 1 through 100.');
    path = `/api/issues?limit=${limit}`;
  } else if (command === 'create' && args.length === 2) {
    path = '/api/issues'; method = 'POST'; body = { ...object(args[1]), projectId: identifier(args[0]) };
  } else if (command === 'update' && args.length === 2) {
    path = `/api/issues/${identifier(args[0])}`; method = 'PATCH'; body = object(args[1]);
  } else if (command === 'comment' && args.length === 2 && args[1].trim()) {
    path = `/api/issues/${identifier(args[0])}/comments`; method = 'POST'; body = { body: args[1], internal: false };
  } else throw new Error(usage);

  async function request(route) {
    let response;
    try {
      response = await fetch(new URL(route, base), { method, redirect: 'manual', signal: AbortSignal.timeout(10_000),
        headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
        ...(body ? { body: JSON.stringify(body) } : {}) });
      if (!response.ok) {
        await response.body?.cancel();
        const retry = response.headers.get('retry-after');
        const seconds = retry && /^\d{1,10}$/.test(retry) ? retry : null;
        throw new Error(`HTTP ${response.status}${seconds ? `; Retry-After: ${seconds} seconds` : ''}. No retry was sent.`);
      }
      return await response.json();
    } catch (error) {
      if (error.message.startsWith('HTTP ')) throw error;
      throw new Error(method === 'GET' ? 'Request failed, timed out or returned invalid JSON.' : 'Write outcome unknown. Check the ticket before repeating this command.');
    }
  }

  if (method !== 'GET') print(process.stdout, JSON.stringify(await request(path)));
  else {
    let cursor = null;
    const seen = new Set();
    do {
      const page = await request(path + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''));
      if (!page || !Array.isArray(page.items) || !(page.nextCursor === null || typeof page.nextCursor === 'string' && page.nextCursor.length > 0)) throw new Error('Invalid paginated API response.');
      for (const issue of page.items) print(process.stdout, JSON.stringify(issue));
      cursor = page.nextCursor;
      if (cursor && seen.has(cursor)) throw new Error('API repeated a cursor; pagination stopped.');
      seen.add(cursor);
    } while (cursor);
  }
} catch (error) {
  print(process.stderr, error.message);
  process.exitCode = 1;
}

TIKKETTY_URL=https://tikketty.com python3 api_client.py issues 25
TIKKETTY_URL=https://tikketty.com python3 api_client.py create PROJECT_ID '{"title":"Review the header"}'
TIKKETTY_URL=https://tikketty.com python3 api_client.py update ISSUE_ID '{"status":"todo","priority":"important"}'
TIKKETTY_URL=https://tikketty.com python3 api_client.py comment ISSUE_ID 'Reproduced on staging.'

#!/usr/bin/env python3
"""Dependency-free CLI example; mutation requests are never retried."""
import http.client
import json
import os
import re
import sys
from urllib.parse import urlencode, urlsplit

TOKEN = os.environ.get("TIKKETTY_TOKEN", "")
USAGE = "Usage: api_client.py [issues [limit] | create PROJECT_ID JSON | update ISSUE_ID JSON | comment ISSUE_ID BODY]"


def output(value, stream=sys.stdout):
    print(value.replace(TOKEN, "[redacted]") if TOKEN else value, file=stream)


def identifier(value):
    if not re.fullmatch(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}", value):
        raise ValueError("Use the project or issue UUID from the API.")
    return value


def fields(text):
    try:
        value = json.loads(text)
    except ValueError:
        raise ValueError("JSON must be an object with supported issue fields.") from None
    if not isinstance(value, dict) or not value or set(value) - {"title", "description", "status", "priority", "dueDate"}:
        raise ValueError("JSON must be an object with supported issue fields.")
    return value


def main():
    origin = os.environ.get("TIKKETTY_URL", "http://127.0.0.1:3001")
    if not re.match(r"^https?://", origin) or re.search(r"[\\\s?#]", origin):
        raise ValueError("TIKKETTY_URL must be an HTTPS origin or loopback HTTP origin.")
    try:
        base = urlsplit(origin)
        port = base.port
    except ValueError:
        raise ValueError("Invalid TIKKETTY_URL.") from None
    if base.username or base.password or not base.hostname or base.path not in ("", "/") or (base.scheme == "http" and base.hostname not in ("localhost", "127.0.0.1", "::1")):
        raise ValueError("TIKKETTY_URL must be an HTTPS origin or loopback HTTP origin.")
    if not TOKEN or len(TOKEN) > 8192 or re.search(r"[^\x21-\x7e]", TOKEN):
        raise ValueError("Set TIKKETTY_TOKEN privately to a valid API token.")
    command, *args = sys.argv[1:] or ["issues"]
    method, body = "GET", None
    if command == "issues" and len(args) <= 1:
        limit = args[0] if args else "50"
        if not re.fullmatch(r"[1-9]\d?|100", limit):
            raise ValueError("Page limit must be 1 through 100.")
        path = "/api/issues?" + urlencode({"limit": limit})
    elif command == "create" and len(args) == 2:
        path, method, body = "/api/issues", "POST", {**fields(args[1]), "projectId": identifier(args[0])}
    elif command == "update" and len(args) == 2:
        path, method, body = "/api/issues/" + identifier(args[0]), "PATCH", fields(args[1])
    elif command == "comment" and len(args) == 2 and args[1].strip():
        path, method, body = "/api/issues/" + identifier(args[0]) + "/comments", "POST", {"body": args[1], "internal": False}
    else:
        raise ValueError(USAGE)

    def request(route):
        connection = (http.client.HTTPSConnection if base.scheme == "https" else http.client.HTTPConnection)(base.hostname, port, timeout=10)
        try:
            headers = {"Authorization": "Bearer " + TOKEN, "Accept": "application/json"}
            if body is not None:
                headers["Content-Type"] = "application/json"
            connection.request(method, route, body=json.dumps(body).encode() if body is not None else None, headers=headers)
            response = connection.getresponse()
            if not 200 <= response.status < 300:
                retry = response.getheader("Retry-After", "")
                suffix = "; Retry-After: " + retry + " seconds" if re.fullmatch(r"\d{1,10}", retry) else ""
                raise ValueError("HTTP " + str(response.status) + suffix + ". No retry was sent.")
            return json.loads(response.read())
        except ValueError as error:
            if str(error).startswith("HTTP "):
                raise
            raise ValueError("Request failed, timed out or returned invalid JSON." if method == "GET" else "Write outcome unknown. Check the ticket before repeating this command.") from None
        except (OSError, http.client.HTTPException):
            raise ValueError("Request failed, timed out or returned invalid JSON." if method == "GET" else "Write outcome unknown. Check the ticket before repeating this command.") from None
        finally:
            connection.close()

    if method != "GET":
        output(json.dumps(request(path)))
        return
    cursor, seen = None, set()
    while True:
        page = request(path + ("&" + urlencode({"cursor": cursor}) if cursor else ""))
        if not isinstance(page, dict) or not isinstance(page.get("items"), list) or "nextCursor" not in page or not (page["nextCursor"] is None or isinstance(page["nextCursor"], str) and page["nextCursor"]):
            raise ValueError("Invalid paginated API response.")
        for issue in page["items"]:
            output(json.dumps(issue))
        cursor = page["nextCursor"]
        if not cursor:
            return
        if cursor in seen:
            raise ValueError("API repeated a cursor; pagination stopped.")
        seen.add(cursor)


if __name__ == "__main__":
    try:
        main()
    except ValueError as error:
        output(str(error), sys.stderr)
        sys.exit(1)