API Reference¶

The AMP API is a RESTful JSON API that allows you to programmatically manage content missions, review generated content, and access analytics.

Base URL¶

https://api.amp.dev/v1

For self-hosted deployments:

https://your-domain.com/api/v1

Authentication¶

All API requests require authentication via API key or JWT token:

curl https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer amp_live_xxxxxxxxxxxxxxxxxxxx"

See Authentication for details on obtaining and managing API keys.

Request Format¶

Headers¶

Request Body¶

Send JSON for POST and PUT requests:

curl -X POST https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Mission",
    "objectives": ["Drive awareness"],
    "platforms": ["twitter"]
  }'

Response Format¶

Success Response¶

{
  "id": "msn_2xK9mPqR4vN8sT3w",
  "name": "My Mission",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

List Response¶

{
  "data": [
    {"id": "msn_xxx", "name": "Mission 1"},
    {"id": "msn_yyy", "name": "Mission 2"}
  ],
  "has_more": true,
  "total": 45
}

Error Response¶

{
  "error": {
    "code": "invalid_request",
    "message": "The 'platforms' field is required",
    "param": "platforms",
    "doc_url": "https://docs.amp.dev/api/errors#invalid_request"
  }
}

Pagination¶

List endpoints support cursor-based pagination:

# First page
curl "https://api.amp.dev/v1/missions?limit=20"

# Next page
curl "https://api.amp.dev/v1/missions?limit=20&starting_after=msn_xxx"

# Previous page
curl "https://api.amp.dev/v1/missions?limit=20&ending_before=msn_yyy"

Parameters¶

Filtering¶

Many list endpoints support filtering:

# Filter by status
curl "https://api.amp.dev/v1/missions?status=active"

# Filter by date range
curl "https://api.amp.dev/v1/content?created_after=2024-01-01&created_before=2024-02-01"

# Multiple filters
curl "https://api.amp.dev/v1/content?mission_id=msn_xxx&status=published&platform=twitter"

Expanding Objects¶

Some endpoints support expanding related objects:

# Include mission details with content
curl "https://api.amp.dev/v1/content/cnt_xxx?expand=mission"

{
  "id": "cnt_xxx",
  "mission_id": "msn_yyy",
  "mission": {
    "id": "msn_yyy",
    "name": "Developer Outreach"
  }
}

Rate Limits¶

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1705319400

Versioning¶

The API is versioned via URL path (/v1/). We maintain backward compatibility within a version.

Breaking changes are introduced in new versions with a deprecation period for old versions.

API Endpoints¶

Authentication¶

Missions¶

Content¶

Publishing¶

Analytics¶

Integrations¶

SDKs¶

Official SDKs are available:

• Go SDK
• TypeScript SDK

Testing¶

Use test mode API keys (amp_test_xxx) to experiment without publishing real content:

curl https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer amp_test_xxxxxxxxxxxx"

Test mode:

• Does not publish to real platforms
• Uses sandbox provider endpoints
• Has separate rate limits
• Data is periodically cleared