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.

​
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 the current actions workspace, including active recommendations and adopted backlog work
  • Trigger command-center brief generation for a specific action
  • 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 Knowledge explains which profile changes apply immediately and which require review.

​
Actions Endpoint Notes

The actions endpoint reflects the current workspace model:
  • surface lets you filter between recommendation and backlog
  • detailLevel=summary is default; detailLevel=context adds bounded why-now context, scores, metrics, top evidence, brief readiness, and follow-up links
  • status uses public workspace states: active, backlog, in_progress, blocked, done, canceled
  • active applies to recommendations; the rest apply to adopted backlog work
  • The aliases open, completed, and dismissed are also accepted for compatibility and map to backlog, done, and canceled

​
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.
  • Outcomes 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. 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