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
`GET /projects/{projectId}/pages/metrics`	List unified page metrics
`GET /projects/{projectId}/pages/guard-rails`	List page guard-rail findings
`GET /projects/{projectId}/audit/summary`	Get Audit summary
`GET /projects/{projectId}/audit/findings`	List Audit findings
`GET /projects/{projectId}/audit/eligibility`	Get Google eligibility evidence
`GET /projects/{projectId}/outcomes/ledger`	List measured outcomes
`GET /projects/{projectId}/traffic/referrals`	List AI referrals
`GET /projects/{projectId}/traffic/404-demand`	Get 404 Demand
`GET /projects/{projectId}/traffic/direct-lift`	Get AI-correlated Direct lift
`GET /projects/{projectId}/agents`	List managed agents
`GET /projects/{projectId}/agents/runs`	List managed-agent runs
`GET /projects/{projectId}/agents/runs/{runId}`	Get a managed-agent run
`POST /projects/{projectId}/agents/{agentKey}/runs`	Trigger a managed-agent run
`GET /projects/{projectId}/visibility/summary`	Get visibility summary metrics
`GET /projects/{projectId}/citations/stats`	Get aggregate citation statistics
`GET /projects/{projectId}/citations/top-domains`	Get top citation domains
`GET /projects/{projectId}/citations/top-pages`	Get top citation pages
`GET /projects/{projectId}/visibility/diff`	Get visibility diff
`GET /projects/{projectId}/content-gaps/list`	List content gaps
`GET /projects/{projectId}/competitive/position`	Get competitive positioning data
`GET /projects/{projectId}/adoption/metrics`	Get adoption metrics
`GET /projects/{projectId}/actions/list`	List actions
`GET /projects/{projectId}/actions/{actionId}/brief`	Get action brief
`POST /projects/{projectId}/actions/{actionId}/brief`	Generate action brief
`GET /projects/{projectId}/traffic/summary`	Get traffic summary
`GET /projects/{projectId}/traffic/platforms`	Get traffic by platform
`GET /projects/{projectId}/intelligence/anomalies`	Detect intelligence anomalies
`GET /projects/{projectId}/intelligence/what-works`	Get what-works recommendations
`GET /projects/{projectId}/webhooks`	List webhook subscriptions
`POST /projects/{projectId}/webhooks`	Create webhook subscription
`DELETE /projects/{projectId}/webhooks/{webhookId}`	Delete webhook subscription
`POST /projects/{projectId}/webhooks/{webhookId}/rotate-secret`	Rotate webhook signing secret

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.

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

Visibility summaries, competitive position, citation stats, top pages, top domains, content gaps, traffic summary, traffic platforms, adoption metrics, what-works recommendations, visibility diff, and intelligence anomalies 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, 28, or 90 and default to 28.
Outcomes Ledger accepts windowDays=7, 28, 90, or 365 and defaults to 28.
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

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