API reference

Use the Sigvane API when you want your own worker, script, service, or agent to read inbox items directly.

The CLI uses this same API. If you only need to run a local command for each inbox item, start with CLI getting started instead.

Base URL

https://api.sigvane.com

All paths below are relative to this base URL.

Authentication

API requests use an account API key:

Authorization: Bearer <key_id>.<secret>

Create an API key in the Sigvane web app. Treat the full token like a password.

Requests without a valid API key return 401.

Error Responses

Use the HTTP status code as the stable error signal.

Common statuses:

• 400: malformed request, such as an invalid cursor or non-positive limit
• 401: missing or invalid API key
• 404: inbox not found, deleted, or not owned by the authenticated account

Error response bodies are not part of the public contract.

List Inboxes

GET /v1/inboxes

Returns inboxes owned by the authenticated account.

Example:

curl https://api.sigvane.com/v1/inboxes \
  -H "Authorization: Bearer $SIGVANE_API_KEY"

Response:

{
  "content": [
    {
      "id": "00000000-0000-7000-8000-000000000456",
      "slug": "github-repo",
      "provider": "github",
      "webhookUrl": "https://api.sigvane.com/webhooks/00000000-0000-7000-8000-000000000456",
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-04-01T10:00:00Z",
      "lastReceivedAt": "2026-04-03T10:05:00Z"
    }
  ]
}

lastReceivedAt is null when Sigvane has not accepted a delivery for that inbox yet.

List Inbox Items

GET /v1/inboxes/{inboxId}/items

Use this endpoint for durable worker polling. It returns inbox items oldest first for one inbox.

Query parameters:

Name	Required	Description
cursor	No	The last nextCursor value you saved. Must be an inbox item id.
limit	No	Positive integer. Defaults to 20; values above 100 are capped to 100.

First request:

curl "https://api.sigvane.com/v1/inboxes/00000000-0000-7000-8000-000000000456/items?limit=20" \
  -H "Authorization: Bearer $SIGVANE_API_KEY"

Response:

{
  "items": [
    {
      "id": "00000000-0000-7000-8000-000000000123",
      "inboxId": "00000000-0000-7000-8000-000000000456",
      "inbox": "github-repo",
      "recordedAt": "2026-04-03T10:00:00Z",
      "expireAt": "2026-04-06T10:00:00Z",
      "headers": {
        "x-github-event": [
          "push"
        ],
        "x-github-delivery": [
          "11111111-2222-3333-4444-555555555555"
        ],
        "content-type": [
          "application/json"
        ]
      },
      "body": "eyJzZXF1ZW5jZSI6MX0=",
      "providerDeliveryId": "11111111-2222-3333-4444-555555555555"
    }
  ],
  "nextCursor": "00000000-0000-7000-8000-000000000123"
}

To continue, pass nextCursor back as cursor:

curl "https://api.sigvane.com/v1/inboxes/00000000-0000-7000-8000-000000000456/items?cursor=00000000-0000-7000-8000-000000000123&limit=20" \
  -H "Authorization: Bearer $SIGVANE_API_KEY"

Cursor behavior:

• With no cursor, Sigvane starts at the oldest retained inbox item.
• With a cursor, Sigvane returns items after that inbox item id.
• When items is not empty, nextCursor is the last returned item id.
• When no later items exist and you sent a cursor, nextCursor echoes that cursor.
• When the inbox is empty and you did not send a cursor, nextCursor is null.

Persist the latest nextCursor after your worker has successfully handled the returned items.

List Recent Inbox Items

GET /v1/inboxes/{inboxId}/items/recent

Use this endpoint for inspection and setup checks. It returns the newest inbox items first and does not use a cursor.

Query parameters:

Name	Required	Description
limit	No	Positive integer. Defaults to 20; values above 100 are capped to 100.

Example:

curl "https://api.sigvane.com/v1/inboxes/00000000-0000-7000-8000-000000000456/items/recent?limit=5" \
  -H "Authorization: Bearer $SIGVANE_API_KEY"

Response:

{
  "content": [
    {
      "id": "00000000-0000-7000-8000-000000000125",
      "inboxId": "00000000-0000-7000-8000-000000000456",
      "inbox": "github-repo",
      "recordedAt": "2026-04-03T10:10:00Z",
      "expireAt": "2026-04-06T10:10:00Z",
      "headers": {
        "x-github-event": [
          "ping"
        ],
        "x-github-delivery": [
          "33333333-4444-5555-6666-777777777777"
        ]
      },
      "body": "eyJ6ZW4iOiJkZXNpZ24gZm9yIGZhaWx1cmUifQ==",
      "providerDeliveryId": "33333333-4444-5555-6666-777777777777"
    }
  ]
}

Use the inbox feed endpoint when your worker needs to process older retained items or maintain progress with a cursor.

Inbox Item Fields

Each inbox item has the same shape in the feed and recent-items endpoints.

Field	Description
id	Sigvane-generated inbox item id.
inboxId	Immutable id of the inbox that owns the item.
inbox	Inbox slug at the time the item is returned.
recordedAt	Time Sigvane recorded the inbox item.
expireAt	Time after which Sigvane may delete the inbox item.
headers	Filtered request headers. Keys are lowercased and values are arrays.
body	Raw request body encoded as base64.
providerDeliveryId	Provider delivery id when available. For GitHub, this comes from X-GitHub-Delivery.

Sigvane does not parse GitHub payloads into provider-specific top-level fields. Decode body before parsing the GitHub JSON payload.

See Webhook signatures and stored data for more detail about accepted deliveries and stored headers.