Skip to main content
DevTune provides a public REST API for integrating your AI search visibility data into CI/CD pipelines, BI tools, custom dashboards, and automated workflows. Most endpoints are read-focused analytics endpoints. API keys also power webhook management and non-interactive MCP clients, while MCP clients that support OAuth can use browser sign-in and project selection instead. The Results API keeps the /outcomes/ path and the devtune_get_outcomes_ledger tool name for compatibility.

​
What You Can Do

With the DevTune API you can:
  • Pull visibility metrics (share of voice, presence rate, brand mentions) into your reporting tools
  • Monitor competitive positioning trends programmatically
  • Feed citation data into your own analytics pipelines
  • Track adoption metrics (npm downloads, GitHub stars) alongside search visibility
  • Pull your actions: what DevTune suggests, what your team accepted, what is live and what was archived
  • Trigger brief generation for an action DevTune suggested
  • List, search, read, upload, and version project Library items
  • Read and directly edit the Knowledge Profile, and review proposed profile changes
  • Build custom alerting on top of DevTune data
  • Connect AI coding agents (Codex, Claude, Cursor) via the MCP server for in-IDE access

​
Requirements

  • A Plus plan or higher with API access enabled
  • An API key scoped to a specific project

​
Available Endpoints

The legacy intelligence anomaly endpoint and MCP tool are retired. For detected changes and events, use GET /projects/{projectId}/timeline/events over REST or the devtune_get_timeline_events MCP tool. Both require the visibility.read scope.
Tip: Full request/response documentation for each endpoint is available in the Endpoints section of the API Reference sidebar, auto-generated from the OpenAPI specification.
The webhooks guide documents real-time event notifications, and the MCP server guide covers agent access. The machine-readable specification is available at GET /api/v2/openapi.json. The Library guide covers catalog and version behavior, while Project context explains which profile changes apply immediately and which require review.

​
Actions Endpoint Notes

Every action is in one of four states:
  • suggested — DevTune proposed it and nobody has decided
  • accepted — your team wants it done
  • live — the page is published; its measurement is running or complete
  • archived — your team took it off the queue
Filter with status; without it the list returns every state, suggested actions first in rank order. blocked is true on accepted work your team has marked blocked. detailLevel=summary is default; detailLevel=context adds bounded why-now context, scores, metrics, top evidence, brief readiness, and follow-up links.

​
Citations vs Mentions

Public citation endpoints are named /citations/* because they describe cited sources: pages, domains, classifications, positions, and evidence references. “Mentions” has a separate DevTune meaning: brand or product mentions inside AI answer text. Public windowed REST endpoints use windowDays with endpoint-specific fixed rolling windows. Citation top-list endpoints use cursor pagination. Pass pageSize up to 100; when a response includes nextCursor, send it as cursor to retrieve the next page. Citation top-list endpoints support simple prefix matching on URL and/or canonical domain. Content gaps use offset and limit, with an optional gapType and display-label search. The public API does not support arbitrary sort columns, classification filters, broad content/source filters, or citation compare requests.

​
Content gaps contract change

GET /projects/{projectId}/content-gaps/list now returns measured topic, source, and brand rollup facts over a fixed 30- or 90-day window. Each item includes its stable key and label, citation counts split into primary and competitor, average position, primary share when it can be calculated, and the rollup watermark date. estimated is always false. Sources and brands you own are excluded, as are topics you hold at least half the citations on. Those are your presence rather than a gap, and they are absent from both the list and totalCount. A topic where others hold most of the citations is a gap even when you are cited on it too; read share to see how much of it is yours. Every count on this resource is a citation. Content-gap rollups are built only from cited results, so the endpoint reports no mention counts. This is a breaking change. The resource no longer returns impactScore, confidenceScore, freshnessScore, actionabilityScore, signalStrength, signals, evidence, candidateKey, summary, prompt counts, or third-party citation counts. Those pipeline-derived fields cannot be reproduced from the measurement rollups, so the API does not substitute estimates. When the content-gap window has not been rolled up, coverage.status is unavailable and the list is empty. An available window still reports availableDays and isPartial, because a finalized rollup can cover fewer days than the window you asked for. Read the counts against availableDays, not against windowDays. coverage.asOfDate and the returned window both end on the rollup watermark, which trails today whenever the content-gap lane has not caught up.

​
Response Caching

Read-focused analytics endpoints may return short-lived cached responses to reduce repeated polling overhead. Clients should respect the Cache-Control response header. If an integration needs to force a fresh read, send Cache-Control: no-cache with the request.

​
Fixed Windows

  • Visibility summaries, competitive position, citation stats, top pages, top domains, content gaps, traffic summary, traffic platforms, adoption metrics, what-works recommendations, and visibility diff accept windowDays=30 or 90 and default to 30.
  • Page metrics, Audit summary, Audit eligibility, AI referrals, and AI-correlated Direct lift accept windowDays=7, 30, or 90 and default to 30.
  • Results Ledger accepts windowDays=7, 30, 90, or 365 and defaults to 30.
  • Responses expose the resolved selection as window or windowDays, depending on the endpoint. Use the response schema for that endpoint instead of assuming one shared shape.

​
Action Brief Write Operation

Use POST /api/v2/projects/{projectId}/actions/{actionId}/brief to generate or reuse an execution-ready action brief. Briefs exist for actions DevTune suggested, including ones created from a prompt; an action made with Create Action has no brief, and its ID returns Action not found. This endpoint requires the actions.write API key scope. It does not create duplicate work for briefs that are already ready or generating. The response returns the current state:
  • ready: a usable brief already exists
  • generating: background generation is already running
  • queued: DevTune queued generation and returned an eventId
After a queued or generating response, use GET /api/v2/projects/{projectId}/actions/{actionId}/brief to poll for status: "ready" and retrieve briefMarkdown. You can optionally send briefStyle in the request body to ask for best_fit or a specific allowed content format. If project content preferences are enabled, the requested style must be allowed for the project.

​
Getting Started

  1. Create an API key from API Keys in the account sidebar
  2. Make your first request using the key in the Authorization header
  3. Explore the endpoints to find the data you need
For OAuth-based agent access, connect through the MCP server instead of creating an API key.

​
Quick Example

​
Generate an Action Brief

​
Positioning match

Both positioning endpoints require attributes.read and access to positioning match. The list returns each statement’s ID, kind, relevant intents, status and creation time. The match endpoint accepts window=30 or 90, defaulting to 30, and optional platform and intent filters. Match results include counts, brand IDs and names, daily counts, and share_of_attribute for the project’s primary brand. Share divides that brand’s count by all brand_counts plus another_product. The several and nobody counts are returned separately and excluded from the denominator. A denominator below ten returns a null share. Competitor changes and the series start date identify the comparison period. Each statement also compares with the previous window of the same length, given as prior_window. prior_status is comparable when both windows measured the current competitor set and the previous one was scored on every day, platform and intent it had eligible answers for. prior then holds the previous window’s totals and its share_of_attribute. Otherwise prior_status is competitor_changed or incomplete, and prior is null.