> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.markup.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.markup.ai/_mcp/server.

# Quickstart

> Markup AI API quickstart

The Markup AI API lets you run **content agents** — Brand Voice, Sentence Clarity, Terminology, and more — against your text and get back flagged issues with suggested fixes. Follow this guide to run your first agent over HTTP.

## Using the Markup AI API

#### Get Your API Key

[Create an account](https://console.markup.ai/signup), configure your brand voice and style settings in the console, then copy your API key. You'll send it as a Bearer token: `Authorization: Bearer YOUR_API_KEY`.

#### Run Your First Agent

Agents are run by ID, but you never hardcode one — resolve the ID from the agent's stable `name` with `GET /agents`, then `POST /agents/{agent_id}/run` with your content as `text`. This example runs **Brand Voice** (`brand_voice`), which flags passages that have drifted from your approved brand voice and shares suggestions.

> **Tip**
>
> Agents run against the brand voice, personas, terminology, and style guide configured for your organization in the [console](https://console.markup.ai) — there are no per-call style guide IDs. Pass `wait=true` to block until the run finishes; omit it to get a `workflow_id` back immediately and track the run with `GET /agents/workflows/{workflow_id}`.

**`cURL`**

```bash title="cURL"
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.markup.ai"

# 1) Resolve the Brand Voice agent ID from its name
AGENT_ID=$(curl -s "$BASE_URL/agents?page_size=100" \
  -H "Authorization: Bearer $API_KEY" \
  | jq -r '.agents[] | select(.name == "brand_voice") | .id')

# 2) Run the agent and wait for the result
curl -X POST "$BASE_URL/agents/$AGENT_ID/run?wait=true" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Our cutting-edge solution leverages synergies to maximize value."}'
# -> { "status": "completed", "result": { ... } }
```

**`Python`**

```python title="Python"
# example.py — uses the `requests` library: pip install requests
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.markup.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1) Resolve the Brand Voice agent ID from its name
agents = requests.get(
    f"{BASE_URL}/agents", headers=headers, params={"page_size": 100}
).json()["agents"]
agent_id = next(a["id"] for a in agents if a["name"] == "brand_voice")

# 2) Run the agent and wait for the result
response = requests.post(
    f"{BASE_URL}/agents/{agent_id}/run",
    headers=headers,
    params={"wait": "true"},
    json={"text": "Our cutting-edge solution leverages synergies to maximize value."},
)
response.raise_for_status()
result = response.json()
print(result["status"], result.get("result"))
```

**`TypeScript`**

```typescript title="TypeScript"
// example.ts — uses the built-in fetch (Node.js 18+)
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.markup.ai";
const headers = { Authorization: `Bearer ${API_KEY}` };

const main = async () => {
  // 1) Resolve the Brand Voice agent ID from its name
  const { agents } = await (
    await fetch(`${BASE_URL}/agents?page_size=100`, { headers })
  ).json();
  const agentId = agents.find((a) => a.name === "brand_voice").id;

  // 2) Run the agent and wait for the result
  const result = await (
    await fetch(`${BASE_URL}/agents/${agentId}/run?wait=true`, {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({
        text: "Our cutting-edge solution leverages synergies to maximize value.",
      }),
    })
  ).json();

  console.log(result.status, result.result);
};

main();
```

#### Run the code

**`Python`**

```bash title="Python"
python3 example.py
```

**`TypeScript`**

```bash title="TypeScript"
npx tsx example.ts
```

## Personas and Brand Voice Profiles

The persona and brand voice agents tailor their output to a saved configuration that you reference by ID:

* **Personas** shape feedback for a specific audience or reviewer. Pass a persona's ID as `persona_id` when you run the persona agent.
* **Brand voice profiles** capture how your brand should sound. Pass a profile's ID as `voice_profile_id` when you run the brand voice agent.

You create and edit both in the Console. To find the IDs to send to the API, list them:

```bash
curl https://api.markup.ai/personas \
  -H "Authorization: Bearer YOUR_TOKEN"

curl https://api.markup.ai/brand-voice-profiles \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Each entry in the response includes an `id` — use it as the `persona_id` or `voice_profile_id`. The full response shapes are documented under Personas and Brand Voice Profiles in the [API Reference](/api-reference).

Want the full agent list and per-agent examples? See [Running Agents](/developer/agents). For every endpoint, see the [API Reference](/api-reference).