> ## 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 REST API Reference

> Integrate DevTune visibility metrics, citations, adoption data, and webhooks into CI/CD pipelines, BI tools, and dashboards with the public REST API.

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](/api-reference/webhooks)**     | Real-time event notifications                                                   |
| **[MCP Server](/api-reference/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

1. **[Create an API key](/api-reference/authentication)** 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](/api-reference/mcp-server) instead of creating an API key.

## Quick Example

```bash theme={null}
curl -H "Authorization: Bearer dtk_live_your_key_here" \
  "https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary"
```

```json theme={null}
{
  "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

```bash theme={null}
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"
```

```json theme={null}
{
  "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"
  }
}
```

## Related Documentation

* **[Authentication](/api-reference/authentication)** - API key creation and usage
* **[Rate Limits](/api-reference/rate-limits)** - Request limits by plan tier
* **[Error Handling](/api-reference/errors)** - Error codes and troubleshooting