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"

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:

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.

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.