Developer Reference

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

1

Get Your API Key

Create an account, 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.

2

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.

Agents run against the brand voice, personas, terminology, and style guide configured for your organization in the console — 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}.

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": { ... } }
3

Run the code

python3 example.py

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:

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.

Want the full agent list and per-agent examples? See Running Agents. For every endpoint, see the API Reference.