API Documentation

Access your Content Intelligence data programmatically. Available on Pro and Enterprise plans.

Authentication

All API requests require a Bearer token in the Authorization header. Generate an API key from your Settings page.

curl -H "Authorization: Bearer ci_live_abc123..." \
  https://content.yallapublish.com/api/v1/projects

Rate Limiting

Requests are rate-limited per API key using a sliding 1-minute window. Default: 100 requests/minute. Headers included on every response:

HeaderDescription
X-RateLimit-LimitMax requests per window
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetUnix timestamp when the window resets
X-Request-IdUnique request identifier for debugging
X-Response-TimeServer processing time

Projects

GET/api/v1/projects

List all projects in your organization with keyword, content, and social account counts.

Example Response

{
  "data": [
    {
      "id": "clx...",
      "name": "My Website",
      "websiteUrl": "https://example.com",
      "primaryCountry": "US",
      "createdAt": "2025-01-15T10:30:00Z",
      "_count": { "keywords": 142, "contentItems": 38, "socialAccounts": 3 }
    }
  ],
  "total": 1
}

Keywords

GET/api/v1/keywords

Retrieve tracked keywords for a project.

ParamTypeRequiredDescription
projectIdstringrequiredProject ID
pagenumberoptionalPage number (default 1)
limitnumberoptionalResults per page (max 100, default 50)

Example Response

{
  "data": [
    {
      "id": "clx...",
      "keyword": "best seo tools",
      "country": "US",
      "searchVolume": 12100,
      "difficulty": 67,
      "currentRank": 4,
      "createdAt": "2025-02-01T00:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 142, "totalPages": 3 }
}

Rankings

GET/api/v1/rankings

Get historical keyword ranking data.

ParamTypeRequiredDescription
projectIdstringrequiredProject ID
keywordstringoptionalFilter by keyword (contains match)
fromISO dateoptionalStart date filter
toISO dateoptionalEnd date filter
pagenumberoptionalPage number
limitnumberoptionalResults per page (max 100)

Example Response

{
  "data": [
    {
      "id": "clx...",
      "keyword": "best seo tools",
      "position": 4,
      "previousPosition": 6,
      "change": 2,
      "url": "https://example.com/blog/best-seo-tools",
      "searchVolume": 12100,
      "country": "US",
      "device": "desktop",
      "checkedAt": "2025-03-10T08:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 500, "totalPages": 10 }
}

Content

GET/api/v1/content

List content items for a project.

ParamTypeRequiredDescription
projectIdstringrequiredProject ID
statusstringoptionalFilter by status (DRAFT, SCHEDULED, PUBLISHED, etc.)
pagenumberoptionalPage number
limitnumberoptionalResults per page (max 100)

Example Response

{
  "data": [
    {
      "id": "clx...",
      "title": "Complete Guide to SEO",
      "slug": "complete-guide-to-seo",
      "status": "PUBLISHED",
      "seoScore": 92,
      "wordCount": 2450,
      "scheduledFor": null,
      "publishedAt": "2025-03-01T14:00:00Z",
      "focusKeyword": "seo guide",
      "pageType": "blog_post"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 38, "totalPages": 1 }
}

Social Analytics

GET/api/v1/social/analytics

Aggregated social media analytics and post metrics.

ParamTypeRequiredDescription
projectIdstringrequiredProject ID
platformstringoptionalFilter by platform (instagram, twitter, linkedin, etc.)
fromISO dateoptionalStart date
toISO dateoptionalEnd date

Example Response

{
  "data": {
    "accounts": [
      { "id": "clx...", "platform": "instagram", "handle": "@mybrand" }
    ],
    "analytics": [
      {
        "date": "2025-03-10T00:00:00Z",
        "followers": 15200,
        "followersGrowth": 120,
        "totalReach": 45000,
        "avgEngagementRate": 3.2
      }
    ],
    "posts": {
      "total": 24,
      "totalLikes": 8540,
      "totalComments": 312,
      "totalShares": 198,
      "totalReach": 125000
    }
  }
}

SERP Features

GET/api/v1/serp-features

Detected SERP features and ownership data.

ParamTypeRequiredDescription
projectIdstringrequiredProject ID
keywordstringoptionalFilter by keyword (contains match)
pagenumberoptionalPage number
limitnumberoptionalResults per page (max 100)

Example Response

{
  "data": [
    {
      "id": "clx...",
      "keyword": "best seo tools",
      "featureType": "featured_snippet",
      "ownsFeature": true,
      "createdAt": "2025-03-10T08:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 85, "totalPages": 2 }
}

Error Codes

StatusMeaning
400Bad Request — Missing or invalid parameters
401Unauthorized — Invalid or missing API key
403Forbidden — Insufficient scope or plan
404Not Found — Resource not found or access denied
429Too Many Requests — Rate limit exceeded
500Internal Server Error
{
  "error": "Description of what went wrong"
}

Ready to get started?

Generate your API key from the Settings page and start building integrations.

Get your API Key