Tickets API

The Tickets API works with NOCK-native tickets. Linear is optional: if a project has Linear connected, NOCK can sync with Linear, but the API always reads and writes the NOCK ticket record.

List projects

Use projects first to find the project_id and available categories for an API key:

curl -sS "https://nocknock.cloud/api/v1/projects" \
  -H "Authorization: Bearer $NOCK_API_KEY"

A project-scoped key returns only its assigned project.

List tickets

curl -sS "https://nocknock.cloud/api/v1/tickets?project_id=$NOCK_PROJECT_ID&status=open&limit=20" \
  -H "Authorization: Bearer $NOCK_API_KEY"

Query parameter	Required	Description
`project_id`	Yes	NOCK project UUID.
`page`	No	Page number, default `1`.
`limit`	No	`1` to `50`, default `20`.
`status`	No	`open`, `all`, or a concrete NOCK status.
`category`	No	Category key.
`sort`	No	`newest`, `oldest`, or `status`.

Open tickets exclude completed terminal states. Use status=all when you need the full project history.

Create a ticket

curl -sS -X POST "https://nocknock.cloud/api/v1/tickets" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$NOCK_PROJECT_ID"'",
    "title": "Checkout fails on Safari",
    "description": "Customer reports a blank screen after clicking Pay.",
    "reporter_email": "client@example.com",
    "category": "bug",
    "page_url": "https://example.com/checkout",
    "browser_name": "Safari",
    "os_name": "macOS",
    "viewport_width": 1440,
    "viewport_height": 900,
    "console_logs": [
      {
        "level": "error",
        "message": "Payment widget failed to load",
        "timestamp": "2026-06-25T12:00:00.000Z"
      }
    ]
  }'

Required fields:

Field	Description
`project_id`	NOCK project UUID.
`page_url`	Page or source URL associated with the report.

Plus at least one of title or description. A request with neither is rejected with 400.

Field	Required	Description
`title`	No	Up to 200 characters. Omit it, or send only whitespace, and NOCK derives one from `description`.
`description`	No	Up to 5000 characters. Required when `title` is omitted.

Not every source system has a natural subject line. Send description alone and NOCK derives the title server-side, before the ticket is written — so the derived title is what the 201 response, the ticket.created webhook, and the Slack message all carry. When a widget submission creates a Linear issue, it receives that submission's materialized title too. There is no later correction.

curl -sS -X POST "https://nocknock.cloud/api/v1/tickets" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$NOCK_PROJECT_ID"'",
    "description": "Checkout fails on Safari\n\nCustomer sees a blank screen after clicking Pay.",
    "page_url": "https://example.com/checkout"
  }'

The derivation prefers the first line, then the first sentence, and otherwise cuts on a word boundary. Query strings and fragments are stripped from URLs in the derived title.

A non-blank title you send is never touched. It is stored byte-identical: not trimmed, not shortened, not rewritten, and never passed to a model. A missing or whitespace-only title is treated as absent and is derived from description. Adapters that mirror NOCK tickets into GitHub or Jira can keep matching on the exact non-blank string they submitted.

Important behavior:

API-created tickets use source: "api".
Ticket creation uses the same quota and billing path as widget and portal tickets.
File uploads and image uploads are not part of the Public API yet.
Linear is not required. Optional Linear sync can run after the NOCK ticket is created.

Read a ticket

curl -sS "https://nocknock.cloud/api/v1/tickets/$NOCK_TICKET_ID" \
  -H "Authorization: Bearer $NOCK_API_KEY"

Ticket detail responses include ticket fields, images, website annotations, and customer-visible replies. Internal notes are never returned by the Public API. images[].storage_url is a short-lived signed URL that expires within five minutes; read the ticket detail again when a fresh URL is needed.

annotations contains widget-captured pins and text-edit suggestions. Pin annotations may reference a screenshot image by screenshot_image_id and include page, viewport, selector, nearby text, and coordinates. Text-edit annotations include original_text, suggested_text, selector context, and optional comments.

Update a ticket

curl -sS -X PATCH "https://nocknock.cloud/api/v1/tickets/$NOCK_TICKET_ID" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Checkout still fails on Safari",
    "description": "Customer confirms the issue after clearing cookies.",
    "category": "bug",
    "reporter_email": "client@example.com",
    "status": "In Progress",
    "priority": "high"
  }'

At least one supported field must be sent.

Field	Values
`title`	Non-empty text, up to 200 characters.
`description`	Text up to 5000 characters, empty string, or `null`.
`category`	Category key, up to 50 characters.
`reporter_email`	Valid email, empty string, or `null`.
`status`	`Backlog`, `Triage`, `Todo`, `In Progress`, `Done`, `Cancelled`, `Duplicate`, or `null`.
`priority`	`low`, `normal`, `high`, or `urgent`.
`assignee_user_id`	Workspace member UUID or `null`.

Empty strings for description and reporter_email are stored as null. Reporter emails are normalized to lowercase.

Add a customer-visible reply

curl -sS -X POST "https://nocknock.cloud/api/v1/tickets/$NOCK_TICKET_ID/notes" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "The customer can reproduce it in a private window too.",
    "reporter_email": "client@example.com"
  }'

This creates a customer-visible reply with author_type: "customer". It is meant for external portals, chatbots, support forms, and automation systems that collect customer follow-up.

This route requires the tickets:reply scope.

Adding a customer-visible reply through the Public API queues the same internal team notification as a Customer Portal reply:

The assigned team member is notified when the ticket has an assignee.
Workspace admins and owners are notified when the ticket is unassigned.
The reply author is not notified when NOCK can identify them by user id or email.
Notifications are debounced per ticket and recipient.
Team members can opt out per workspace from their account settings.

Team email notifications are best-effort: they are queued and sent in the background and never block or roll back the reply. If a notification cannot be queued or delivered, the reply is still accepted.

Team-only internal notes remain dashboard functionality. They are not exposed through the Public API.

Webhook side effects

Ticket creation, ticket updates, status changes, and customer-visible replies can create webhook and email deliveries. If a required webhook delivery cannot be queued for a customer-visible reply, NOCK rolls back the reply and returns 503 Failed to queue reply delivery. Team email notifications are best-effort and never cause this rollback.