DevTune REST API Reference

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
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

Endpoint	Description
Visibility Summary	Share of voice, presence rate, and brand mention metrics
Citation Stats	Aggregate citation totals from the v2 stats rollup
Citation Top Lists	Cursor-paginated top citation domains and pages ordered by citation count
Visibility Diff	Current vs previous visibility window comparison
Competitive Position	Citation comparison between you, competitors, and others over time
Content Gaps	Canonical Actions-system topic and prompt-cluster signals with bounded evidence
Adoption Metrics	npm downloads and GitHub stars trends for your domains
Actions	Actions workspace with active recommendations and backlog items
Action Brief	Stored brief status, generated markdown, and brief-generation requests
Traffic Summary	LLM bot and referral traffic analytics
Traffic Platforms	Traffic breakdown by AI platform
Webhooks	Real-time event notifications
MCP Server	Model Context Protocol server for AI coding agents
OpenAPI Spec	`GET /api/v2/openapi.json` — Machine-readable API specification

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.

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. All public windowed REST endpoints use windowDays with fixed rolling windows. The default is 30. The supported values are 30 and 90. Citation top-list and content-gap 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. The public API does not support contains search, arbitrary sort columns, classification filters, broad content/source filters, or citation compare requests.

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

Use windowDays=30 or 90 for visibility summaries, competitive position, citation stats, top pages, top domains, content gaps, traffic, adoption metrics, what-works recommendations, visibility diff, and intelligence anomalies.
Responses include window: { days, dateFrom, dateTo } so integrations can display the exact server-resolved range.

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

Create an API key from API Keys in the account sidebar
Make your first request using the key in the Authorization header
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

curl -H "Authorization: Bearer dtk_live_your_key_here" \
  "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary"

{
  "data": {
    "totalExecutions": 142,
    "shareOfVoice": 23.5,
    "citationPresence": 68.2,
    "brandAwareness": 45.1,
    "avgPrimaryPosition": 2.3,
    "primaryCitations": 97,
    "competitorCitations": 215
  },
  "meta": {
    "timestamp": "2026-02-08T12:00:00.000Z",
    "projectId": "your-project-id"
  }
}

Generate an Action Brief

curl -X POST \
  -H "Authorization: Bearer dtk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"briefStyle":"best_fit"}' \
  "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/actions/ACTION_ID/brief"

{
  "data": {
    "actionId": "ACTION_ID",
    "eventId": "evt_123",
    "message": "Brief generation started in the background.",
    "status": "queued",
    "success": true
  },
  "meta": {
    "timestamp": "2026-02-08T12:00:00.000Z",
    "projectId": "your-project-id"
  }
}

Authentication - API key creation and usage
Rate Limits - Request limits by plan tier
Error Handling - Error codes and troubleshooting

​What You Can Do

​Requirements

​Available Endpoints

​Actions Endpoint Notes

​Citations vs Mentions

​Response Caching

​Fixed Windows

​Action Brief Write Operation

​Getting Started

​Quick Example

​Generate an Action Brief

​Related Documentation