The SignalKit REST API lets you manage prompts, brands, reports, alerts, and more. Authenticate with an API key in the Authorization: Bearer header. Included with every account.
Requires company administrator authority and creation permission for an API key. Optional domains adds own-brand sites; targetCountries defaults to US; brandGroupId names an active client group. Optional creationId is a stable UUID: retrying the same normalized details returns the saved project with 200 rather than creating another. A changed intent or an ID used elsewhere returns generic creation_id_conflict (409). New creation returns 201 and respects the 999-project safety ceiling.
Project-scoped decisions around the existing Content workflow. On-demand analysis reads saved evidence without model spend; scheduled Growth recipes can run explicitly selected semantic models under allowance ceilings. Keyword collection is a separate explicit request. To do items and outcomes retain source dates; missing measurements never mean zero and observed change does not establish causality.
Read access. Query status, type, source, kind and page. Type is write_page, refresh_page, get_cited, fix_site, track_prompt or set_up; source is a comma list of answers, search_console, search_demand, analytics, cloudflare, shopify, catalogue or site_audit; another value returns 400 with the valid values. The old lane filter is deprecated and mapped to these. Returns 25 ranked findings per page, each with its workType and source, whole-queue state counts, current-status kind, type and source counts, assignable project editors, scoped history, publication impact and the current/previous weekly editions. AI visibility priority uses a relative evidence score when prompts can be compared; missing demand remains unmeasured. Select the project with ?project=slug or ?projectId=uuid.
Read access. Equal 28-day windows anchored to confirmed public readback, with three days reporting lag. Search, traffic and exact-page AI citations retain independent coverage and confounds. No causal claim.
Signed-in editor only. Adds proposed guidance with finding and run provenance. Acceptance remains a separate action in Brand › Guidance. Kinds: preference, fact, exception, covered_ground, rejected_topic. Statement: 1–4,000 characters.
Project write access. Send either a workflow decision or exactly {assigneeProfileId: uuid|null}. Assignment is limited to active organization members who can edit this project and records the human actor. Decisions are accept, dismiss, snooze, reopen or resolve. Dismiss, snooze and resolve require a reason; snooze also requires a future snoozedUntil.
Project write access; six per minute. Re-runs the project's stored-data analysis (no model call) and returns {state, checkedAt, outcome, source, sourceObservedAt}. outcome is done when the analysis moved the item to Done, retired when it retired an untouched New item, still_observed when it still sees it, and not_checkable for content work, an item with a brief, a closed item, or one the stored data cannot confirm.
Read access. The latest 20 requests include state, normalized results, provider task identity and reported cost. This is separate from AI keyword volume.
Project write access and Content allowance. Reserves one unit per request; same-day seed/country/language requests replay. An ambiguous dispatch keeps its reservation and is not silently bought again. Supply an explicit supported country and language.
Project read access. Reads stored Shopify Admin evidence and Git revisions without contacting a provider. Redirect configuration is not public HTTP proof; a Git revision is not deployment proof.
Connection-management authority. Explicitly reads bounded redirect and media-alt evidence for one Shopify destination and replaces its latest stored observation.
Project read access. Returns editable goals, calendar, thresholds, known issues, open proposals and provenance-bearing revision history for the active brand.
One manual round per prompt every seven days, plus ten requests per user per hour. Requires an active configured prompt in a project that is switched on; ambiguous scheduling retries retain their reservation and event IDs for 23 hours.
Returns created or already-tracked outcomes per request ID. Stored suggestion identities preserve authorized provenance and close only after successful persistence.
A segment is a market you compete in: a named subset of a project's prompts plus the brands it counts as competitors. Every project has at least one, the default, named after the project. Pass a segment's id as segmentId to a measurement endpoint to read it inside that segment; leave it out and every figure covers the whole project, exactly as it did before segments existed.
Each row carries its id, slug, whether it is the default, how many prompts it holds (archived included) and, in own roster mode, the brands it compares against.
Track your own brand and competitors across AI responses.
Each row carries its lifetime mention rate and the counts it is a ratio of: eligibleAnswers, mentionedAnswers, metricVersion and mentionRate ({ rate, numerator, denominator, interval }, null until the first recompute). There is no composite score.
Adds a competitor or another brand to compare against. The project's own brand was created with the project; isOwnBrand: true renames that single row rather than adding one.
One measured cohort per request: a calendar range, a platform set, a region set, a query class and — optionally — one segment. Every rate comes with the counts it is a ratio of and a stated reason wherever a figure is withheld; nothing here is a composite score or an average of percentages.
Query: range (7d, 14d, 30d, 90d, 180d or 365d; default 30d) or from and to (YYYY-MM-DD, UTC, paired; the pair wins over a preset), platform and region (comma lists), class (all, non_brand or branded), granularity (day, week or month), segmentId (one segment of the project, from GET /api/segments; absent is the whole project). Returns avgSentiment, sentimentTrend, unreadAlerts, activePrompts, trackedBrands, recentAlerts, range, cohort, health, metrics (mentionRate, citedRate, meanPosition, sentiment, platformCoverage, eligibleAnswers), series, platformSlices, comparison, rankings, shareOfVoice and the Overview block (tiles, seriesBy, buckets, matrix). Every change is compared like for like, on the prompts, platforms and regions both periods measured: basis and likeForLike say what was left out, and a change is withheld with its reason when too little is in common. The cited rate counts only answers whose sources were observable.
Same query parameters as the overview, segmentId included. Returns the same measured block and Overview block plus promptBuckets (each with a guarded delta and a bucket series; the bare change field was removed in September 2026), recentActivity, granularity, range, available (the platforms and regions the filters can be set to) and viewer.canWriteProject.
Query: segmentId (required catalogue UUID). Reads setup, a saved review-only plan and the shared prompt-suggestion allowance without model spend. Product-line segments, topics, questions and applicability use the shared catalogue regardless of import source.
Project write access and active monitoring. Send segmentId. Uses the prompt-suggestion allowance to generate a review-only plan; a current completed plan is reused. Apply separately through segment, prompt and product-scope operations. Generation does not activate billable prompts or invent reference facts. Failed or abandoned work can be explicitly retried using another allowance unit.
Query: segmentId (a catalogue segment), the standard measured range, platform and region filters, plus pagination and product filters. productRole selects all (default), primary, add_on or unclassified products without changing stored answer matching. Returns current catalogue facts separately from the reference snapshots stored with each measured answer. accuracySetup supplies prompt assignment and reviewed fact steps, operation IDs and a Products link; paid matching is explicit. Gift cards and fee-only entries are excluded. Source history_unavailable distinguishes existing catalogue rows from a recorded successful sync.
Project write access. Send segmentId, productId and at least one of turnaround, biomarkerCount, sampleType or fastingRequired. A null value clears its manual override and reveals the connected catalogue value, when one exists. Manual facts survive later catalogue syncs. Saving is free and does not change completed checks; run product matching to assess stored answers against the new facts.
Query: from and to (YYYY-MM-DD or ISO timestamps, paired; last 30 days otherwise), promptId, limit. Returns coverage per exposure state and the top observed queries. A platform that does not expose its searches is reported as unknown, never as zero. Nothing here creates a prompt.
Query: from, to (YYYY-MM-DD), platform, limit (default 25, max 100 landing pages) and offset. Returns pageSummary and calculationCoverage, independently observable native citation support, returned own-domain links, GA4 sessions and key events by assistant and landing page. Small session changes are uncertain. Checkout, cart and account landing pages are excluded before pagination; refresh suggestions require indexed editorial pages. These observations do not establish prompt-level conversion attribution or prove that citations caused visits.
Query: landingPage (exact path or URL), from and to (YYYY-MM-DD, maximum 90 days), and limit (default 20, max 50 values per breakdown). Returns stored sessions, key events and revenue split by country, hostname, source/medium, GA4 session channel group and device. It separates the project's own host from other hosts in the selected GA4 property, labels historical unknown dimensions, and does not contact Google live.
Query: weekStart (YYYY-MM-DD) to pick a stored week; the newest otherwise. Never generates a brief. Returns report (status, summary, findings with server-resolved evidence links, evidence period, model and versions), dataFreshness, nextStep and availableWeeks. A week the model could not write carries an edition written from its measurements alone: status fallback, model deterministic.
Query: from and to (YYYY-MM-DD, within the 30-day retention window). Returns totals, daily, byPlatform, topPaths and a disclosure stating the unit, the undercount and that no identity exists in the data.
Query: projectId (required), from and to (YYYY-MM-DD; default 30 days), granularity (day, week or month). Returns traffic totals, daily series, equal-window deltas and conversions over the settled days of the range: it is read to the newest day GA4 has finished counting, three days before today, and period names the window read. Revenue is in the GA4 property's own currency, currencyCode. conversions.llm counts all GA4 key events; conversions.eventRate is the 0–1 session rate for this project's chosen event among AI-referred sessions, or null when unselected, unmeasured or unavailable. deltas.conversionRate is in percentage points. An event-specific read contacts GA4 even when traffic totals are cached. completeness discloses recovered source totals and partial landing pages.
Latest 100 separately supplied consumer observations, name-presence agreement and recent API-answer candidates with canPair and retained prompt wording. Historical candidates with unknown original wording remain listed but cannot be paired. This selected sample never adjusts dashboard rates. Requires project read access.
Configured requested model or search-surface identity, offered search capability, cadence and active prompt-region schedule. States one measurement attempt per eligible scheduled cell, that successful answers may be zero, and that weekly attempt counts are configured maxima. Whether the provider reported the served model remains per answer. Runs no model and changes no schedule.
Requires write access and resultId, exact promptText, region, samePromptAndRegion:true, consumerText, observedAt and complete. The caller attests the same platform. Complete answers within 24 hours are comparable; other observations are saved but excluded. Retries are deduplicated. Buys no model call.
Retained source links from this project's answers. Explicitly unused retrievals are excluded; legacy links with unknown support remain labelled. Ownership is resolved from current brands. A source belongs to an answer, not to a mention.
Query: view (urls or domains), from and to (paired ISO timestamps or UTC calendar days; a calendar to includes the whole day), limit, offset. Returns rows with link and answer counts, confirmed versus unknown support, ownership, classification, the denominator and pagination. A redirect is counted under its destination. On the first page of a range, metrics carries cited rate over answers whose support was observable.
Query: key (a source key from the list, in either view), from, to, limit, offset. Returns exact period bounds from, to and toInclusive, the citing prompts, the platforms and a bounded sample of the most recent citing answers — a window, not a citation history.
Requires key and write access. Optional view: urls (default) or domains. Reads a cited page and up to two linked same-origin contact pages, returning up to ten published contact links with evidence and explicit failures. No address is guessed, saved or messaged.
Query: from and to, required. Compares the range with the equal range immediately before it and adds citation persistence. Periods return exact from/to bounds and toInclusive; apply < to when false. A period nothing was measured in is insufficient_data, not a list of departures.
Generate and download visibility, prompt performance, and competitor analysis reports in CSV, JSON, or PDF. Generation is synchronous and a period covers at most 31 inclusive days. No file is stored: a download regenerates from current data, so the same report id can return different numbers later. Every output carries a disclosure naming the report, its period, the population it was counted over, the calculation version and the generation time; the JSON output carries it as data and the row keeps it in filters.disclosure.
Requires project write access. Prompt and competitor reports accept region, platform, classes and segmentId filters, replayed on download; an unknown platform is refused (unknown_platform). Topic filters are refused. Visibility reports require an unfiltered project view.
An alert is an episode: one row per signal for as long as it is open, with a shared status (new, acknowledged, resolved) and a per-reader read state. Every episode carries the evidence it was raised on — period, threshold, what was observed, a link and the next action. A resolved episode never re-opens; a recurrence is a new episode.
Query: status, type, severity and kind (repeated or comma-separated), platform, isRead, limit (1-100), offset. kind is what the signal is about: prompt, brand (a competitor), domain (a cited source), check (a data source), slice (the project or one platform), topic, product, traffic (AI-referred visits to the site), or title (an alert from before subjects were stored). Ordered open first, worst severity first, newest last, with counts over the whole matching set, including counts.byKind.
Body: { status: "acknowledged" | "resolved" }. Needs write access to the project; a viewer reads the shelf and closes nothing on it. 409 with a code when the episode is already there or already resolved.
A Deep audit (2 per 30 days) of one public URL: a crawl, deterministic readiness checks, brand probes against the audit model and a synthesised report. A Quick audit (free) is the lighter one a visitor starts from the public page and it is not run through this API. 2 audits per project every 30 days, shared across the dashboard, this API and the MCP connector, and a competitor's audit spends it like your own site's; the allowance is reserved atomically before anything is bought, and a resend of the same request answers with the audit already queued.
Body: url (public http(s)), projectId (required UUID), crawlDepth (integer 0-25, default 10; 0 checks only the submitted page). Needs write access to the project. 409 while the same audit is queued; an idempotent replay may return a cached result, while a new run after a finished audit uses a new allowance. 429 for exhausted allowance or request limits.
Query: projectId to narrow; scope=own selects that project’s own sites, and domain selects an exact host before the 50-row limit. Every project the caller reaches otherwise.
A public shields-style badge stating the project's mention rate over the last 30 rolled-up days, with the counts it is a ratio of and the window. One colour whatever the number: it states a rate and does not grade it.
Query: style (flat or flat-square), format (svg or json). The JSON form is { label, value, rate, numerator, denominator, interval, range, calculationVersion, note, style }. No session is required, but the legacy projectId path segment must contain the current public badge token from Settings › Badge. A writer must enable publication. UUID embeds, private badges and revoked tokens return 404. Rotate or revoke to stop an existing embed.
Account billing across all owned projects. Each active prompt-region in a switched-on project is one $3 monthly unit; a switched-off project is neither measured nor billed, and seats cost nothing. The $6 signup credit applies to Stripe invoices and grants no free prompt allocation. Saving a card does not start billing.
Manage API keys for programmatic access. The full key is shown only once upon creation. A key carries two independent permissions, chosen at creation and not editable afterwards: scope (all or selected) says which projects it reaches, accessMode (read or write) says what it may do inside them, and neither widens the other. A new key is read-only unless it asks for write; a read key is refused every mutation over REST and over the MCP connector alike, where tools/list shows it only the read tools. An optional expiresAt is enforced before any handler runs; no expiry means the key runs until revoked.
API key only. Reports the key's scope, accessMode, canCreateProjects and expiresAt, the projects it can see and the platforms available, so a caller can decide before it tries. A read key may call it.
Access is shared on two separate axes. A company role — Owner, Admin or Member — is what the identity provider records; Owners and Admins reach every project in the company, including ones created later, and manage billing, members and API keys. A Member reaches only the projects a per-project grant names, as a Viewer (read and export) or an Editor (read and change prompts, brands and settings). Members are not billed per seat. Companies, members and invitations are managed in the app with a signed-in session; an API key acts as the person who issued it and carries that person's reach, and is refused on the company endpoints themselves.
Settings
Read or update stored notification configuration and integration choices.
Visible project access. Reads the selected property's registered key events from GA4 and returns events, conversionEvent and registered. A removed event remains named with registered false. Rate-limited to 20 requests per minute per user and integration.
Company integration-management authority. The event must still be registered on this integration's selected GA4 property. A stale event or changed property returns 409; no selected property returns 409. The choice is per project and changing properties clears it.
The content workspace: the reads, plus the two payment starts. The dashboard's own API carries further content routes — creating and revising an artifact, reviewing, approving, publishing, configuring a destination and connecting a provider — which this reference does not cover yet. Content & Growth is a separate subscription from monitoring on the same account, with its own allowance ledger, and the two may invoice on different dates. It has two tiers: Managed offers the drafting platforms ChatGPT, Claude, Perplexity, Gemini, Grok and DeepSeek; BYOK offers GPT-4.1 mini, Claude Sonnet 5.5 or 4.5, and GLM 4.6 only when the matching OpenAI, Anthropic or Z.AI key is connected, and the customer pays those vendor tokens separately. Each tier's price, included units, top-up pack and card-backed trial come from this deployment's Stripe prices: GET /api/content/billing returns them and the billing page shows them before anything is charged. Allowances stay in their original tier. A deployment that has not been given its Stripe price ids answers 503 with content_plan_unconfigured on both payment routes and names what is outstanding, rather than selling at an invented number.
Project-scoped setup, equal 28-day page-performance windows, search-query suggestions and stored demand. Query view=pages for the browser projection: at most 200 page rows, no full queryPages payload, and a truncated flag when more inventory exists; the Page evidence table shows 25 rows at a time. Omit view for the full evidence response. Any other view is 400. Search, Analytics and AI visibility remain separate; missing data is not zero.
Project write access and an active or trialing Content subscription. Send 1–20 keywords and a supported country. Twenty lookups per organization per UTC day are included; duplicate daily requests replay. No model allowance is used.
Publisher browser session. Send destinationId, slug, optional revisionId and activate. Returns the adapter payload and location without writing or buying a model call.
Publisher browser session. Send url, the page's live address. Records the approved piece's head revision as published there, for a project with no connected site destination. Nothing reads the page back; the publication says the URL was declared. One record per revision.
Owner or administrator browser session. Send provider (openai, anthropic, z_ai), label and apiKey. Encrypted at rest; replaces the active key for that provider. No shared-key fallback.
Query: state (comma-separated: idea, brief, draft, in_review, changes_requested, approved), stage (brief, draft, review, published), source (signalkit or existing, with stage=published), brandId, limit (1-100), offset. Stage counts for the whole project come back beside the rows, so a state filter does not change them. stage=published also answers published: the pieces and the indexed pages no piece became, in one list, narrowed by source. Editorial state, run state and publication state are three fields and are never merged. An unrecognised state, stage or source is a 400.
Query: destinationId, linked, limit (1-200). view=work returns only work identities and truncated, without publication history or counts. itemId returns one scoped indexed item as {item:{title,url}|null}, including removed items beyond the list cap; it cannot be combined with list filters or view. One page is one entry: an indexed page carries the artifacts on it as artifacts[], each saying whether it is refreshing the page or is what the page was published from, and those are not repeated as generated entries; counts.total is distinct pages. linked=false is the indexed pages with no artifact at all. An indexed entry's presence is what the last completed index saw, not a live fetch. truncated says when either source had more rows than the limit could carry.
Every revision with its whole body, the checks, reviews, approvals and publication attempts against each, the decision timeline and the publication gate. Approval validity is recomputed on every read from the content hash, the destination's configuration version and the scoring policy — never stored. An artifact you cannot read is a 404, not a 403.
Query: recipeId, limit, runLimit. Runs report used and held allowance units against their pinned per-run ceiling. A run waiting on a person is reported as waiting, never as failed. Recipe kind distinguishes content generation from Growth analysis: the latter reads stored evidence, runs explicitly assigned semantic models under allowance ceilings, and cannot publish. Owners and administrators can configure, enable and pause recipes from Content › Automations.
Query: connectionId. Account-wide, because one installation serves several projects, and narrowed to the bindings your project scope reaches. No credential is in the response.
Read the products Content can use across every catalogue segment. Returns segments, products and monitored. Products retain segmentId, always return attributes as an array and name their CSV, Shopify or Merchant Center source. monitored means at least one prompt is active and unarchived; there are no measurement fields and no monitoring purchase is required.
Project write access. Set monitoringRole to primary, add_on or null on 1–100 active productIds belonging to this project's catalogues. Unknown or foreign products refuse the whole update. Catalogue imports preserve this choice. Suggestions prioritize primary offerings; Products supports the role filter. No matching run or spend.
Project write access. Send csv and optionally segmentId. With no catalogue segment the route validates the CSV, then creates one without prompts or a monitoring purchase; with one it uses it; with several it returns 409 catalog_selection_required and the available segments. Import is free and leaves products omitted from the file unchanged. The limit is 2,000,000 UTF-8 bytes and 5,000 rows; malformed quoting refuses the file. Invalid rows carry physical line numbers.
Query: kind, limit, learningLimit. A material's extracted body is never returned. sourceCounts.modelUsable counts readable, nonempty material for generation. A project with no editorial brand bound answers an empty set rather than 404.
Body: kind (preference, fact, exception, covered_ground or rejected_topic), statement and rationale. Requires a signed-in project editor and a bound editorial brand. API keys cannot propose guidance. Creates a proposal; accept it separately in Brand › Guidance before it influences drafts.
Plan, subscription, allowance balance, this period's included grant, retained top-ups and trial. Every allowance figure is a sum over the immutable ledger, not a stored counter. Owner or administrator in a browser session; an account-wide API key may poll its own spend.
Browser session only, owner or administrator — an API key is refused, because a key that could start a subscription would be a bearer token for the card. Nothing here grants allowance; the grant is minted when Stripe reports the period paid.
Browser session only, owner or administrator. An active or trialing Content subscription is required to buy a card-paid pack; otherwise 409 subscription_required. Purchased units never lapse after cancellation, but spending them again requires a live subscription. packs is 1-100 as an input bound, not a rate card.
Use SignalKit from Claude, Claude Code, Cursor, Cline, Zed or any client that takes a remote MCP server by URL, so you can ask "what's my mention rate this week?" in plain English. The hosted connector at https://app.signalkit.ai/api/mcp exposes 57 typed tools — 33 reads over projects, segments, brands, prompts, the measured overview, query fan-out, data health, the weekly brief, results, sources, alert episodes, audits, reports, billing, settings and the content workspace, and 24 writes that create, change, run or spend. It also exposes list_app_operations to discover registered REST workflows before a connection uses read_app or change_app. The catalog labels mutation input as an authored validation schema or as field hints; for hints, each route remains authoritative for required fields, types and nested objects.
On the content workspace the connector reads the queue, the library and one artifact, can store an idea, brief or draft it wrote itself, and can buy the next revision from SignalKit's own editorial pipeline. Only the last of those spends the content allowance, and its hold is keyed on the artifact and its head revision number — derived by the server, not sent by the caller — so a retry shares a hold and a stale request cannot replay a settled one. Clinical certification and publishing require a signed-in person in the app. API-key agents are also refused destination and recipe management; an OAuth connection retains its signed-in person's ordinary administration role. Each read reports that limit in an authority block rather than leaving the agent to discover it. Discovered app operations that need a signed-in person return a dashboard handoff and execute nothing. While Content & Growth is unpriced on a deployment the two writing tools are refused as subscription_required.
The key's access mode carries into the connector: a read key is offered only the read tools by tools/list and refused a write tool if it calls one anyway; a write key gets all of them. No read tool triggers paid work. An OAuth connection gets every tool, acting with the signed-in person's own projects and role. The connector also exposes list_organizations; its tenant tools accept organizationId when a person belongs to several organizations. A stdio package over the same REST API exists in the source tree for clients that run a command; it is not published to npm.
Connect a client
Copy-paste setup for Claude Code, Cursor and the local stdio server, with read-key guidance, is at /docs/connector. Contact hello@signalkit.ai if your client needs a different connection flow.
Rate Limiting
Limits are ten times higher for API-key callers than for a signed-in browser session. Most endpoints allow 600 requests per minute per API key (60 per browser session); report generation allows 200 per minute per API key (20 per session). Two endpoints are much tighter: POST /api/prompts/{id}/run allows 100 per hour per API key (10 per browser session) — per hour, not per minute — and POST /api/prompts/suggest allows 100 per minute per key (10 per session). When a rate limit is exceeded the API returns 429 Too Many Requests with a Retry-After header.