Skip to content
SignalbyStorytime
Start free

Developers

Signal API and integrations

Connect Signal to your own systems with scoped tokens, documented endpoints and signed deliveries.

Create an accountOpen the signed-in endpoint guide

The signed-in endpoint guide at /settings/api/docs covers authentication, scopes, endpoints, pagination, request limits and signature verification.

Authentication

Scoped access tokens

Create a token in Settings → API. Signal shows it once and stores only its SHA-256 hash. Tokens start with read. Enabling Allow writes adds write access. Send the token as a bearer header:

curl https://your-signal-host/api/v1/mentions?type=media_tag \
  -H "Authorization: Bearer sig_..."

A token is limited to its brand. Responses include cache-control: private, no-store, and errors use { "error": { "code", "message" } }. REST remains read-only; MCP writes require a write-enabled token.

The limit is 300 requests per minute per token, with a 429 response and Retry-After header when exceeded.

REST endpoints

Snake-case JSON. Mentions, collection items and views paginate with next_cursor and after; creators paginate with page and report a total.

Mentions is called the inbox in some identifiers — /api/inbox, inbox_item_id and the MCP shapes. Those names are frozen so integrations keep working; the surface itself is Mentions.

  • GET /api/v1/mentions

    List mentions with supported filters and cursor pagination.

  • GET /api/v1/mentions/{id}

    Read one mention with its creator, engagement, labels and rights status.

  • GET /api/v1/creators

    List creators with sorting and relationship-status filters.

  • GET /api/v1/creators/{id}

    Read one creator with contact details, notes, custom fields and mention history.

  • GET /api/v1/labels

    List workspace labels and colours.

  • GET /api/v1/collections

    List collections; collection items have a nested endpoint.

  • GET /api/v1/views

    List saved Mentions views for reuse in an integration.

  • GET /api/v1/me

    Read the brand and Instagram accounts attached to the token.

  • GET /api/v1/openapi.json

    Download the current OpenAPI specification.

MCP

Connect an MCP client

The MCP endpoint at /api/mcp uses the same bearer token. Read-only tokens expose only read operations.

Write operations remain subject to server-side messaging, comment and rights-request rules.

{
  "url": "https://your-signal-host/api/mcp",
  "headers": { "Authorization": "Bearer sig_..." }
}

  • Read operations

    Read mentions, creators, campaigns, collections, labels, saved views, conversations, comments, analytics, reports, rights and workspace summaries.

  • Permissioned writes

    Write-enabled tokens can organize posts, update creator context, manage campaigns, request rights and send supported replies.

  • Resources and guided prompts

    Use workspace, mention, creator, campaign and collection resources with supported briefing prompts.

How webhook delivery works

  1. Step 1

    Register an endpoint

    Use a public HTTPS address and choose all mentions or one saved view.

  2. Step 2

    Verify the signature

    Validate the event, delivery and timestamped signature headers before accepting the body.

  3. Step 3

    Return success

    Signal records each attempt and response so delivery failures remain visible.

  4. Step 4

    Allow for retries

    Failed deliveries back off on the documented schedule. Signal does not follow redirects.

Signal currently sends mention.created. Send a test delivery before relying on the endpoint.

Worth knowing

  • API, MCP and webhooks are available from Scale. Check the plan comparison for current limits.
  • REST is read-only. MCP writes require a token with write access.
  • The signed-in endpoint guide documents the available endpoints and delivery contract.