Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

EndpointDescription
Visibility SummaryShare of voice, presence rate, and brand mention metrics
Citation StatsAggregate citation totals from the v2 stats rollup
Citation Top ListsCursor-paginated top citation domains and pages ordered by citation count
Visibility DiffCurrent vs previous visibility window comparison
Competitive PositionCitation comparison between you, competitors, and others over time
Content GapsCanonical Actions-system topic and prompt-cluster signals with bounded evidence
Adoption Metricsnpm downloads and GitHub stars trends for your domains
ActionsActions workspace with active recommendations and backlog items
Action BriefStored brief status, generated markdown, and brief-generation requests
Traffic SummaryLLM bot and referral traffic analytics
Traffic PlatformsTraffic breakdown by AI platform
WebhooksReal-time event notifications
MCP ServerModel Context Protocol server for AI coding agents
OpenAPI SpecGET /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.

​
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

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" \
  "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"
  }
}