SEOZilla API Documentation

Retrieve a list of all articles for your account. Articles sent for syndication are excluded — they are published on external placement sites, not your own.

Endpoint

GET /articles

Query Parameters

projectId - Filter by project ID
status - Filter by status (draft, published)
limit - Number of results (default: 50)
offset - Pagination offset (default: 0)
imageHandling - Image URL format (proxy, direct)

Example Request

curl -X GET "https://www.seozilla.ai/api/rest/articles?status=published&limit=10" \
  -H "Authorization: Bearer sz_YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "abc123",
      "title": "10 SEO Tips for 2024",
      "slug": "10-seo-tips-for-2024",
      "summary": "Discover the latest SEO strategies...",
      "status": "published",
      "featuredImage": {
        "url": "https://storage.blob.core.windows.net/...",
        "proxyUrl": "/api/rest/image-proxy?url=...",
        "prompt": "SEO illustration with modern design"
      },
      "featuredVideoId": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
      "featuredVideo": {
        "id": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
        "videoUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../video",
        "posterUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../poster"
      },
      "wordCount": 1523,
      "readingTime": 8,
      "seoScore": 92,
      "keywords": ["SEO", "optimization", "2024"],
      "createdAt": "2024-01-15T10:30:00Z",
      "publishedAt": "2024-01-15T14:00:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Get Article

Retrieve a specific article with full content.

Endpoint

GET /articles/:id

Example Request

curl -X GET "https://www.seozilla.ai/api/rest/articles/abc123" \
  -H "Authorization: Bearer sz_YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "title": "10 SEO Tips for 2024",
    "slug": "10-seo-tips-for-2024",
    "content": "# 10 SEO Tips for 2024\n\nSearch engine optimization...",
    "contentHtml": "<h1>10 SEO Tips for 2024</h1><p>Search engine optimization...</p>",
    "summary": "Discover the latest SEO strategies...",
    "metaDescription": "Learn the top 10 SEO tips for 2024...",
    "seoTitle": "10 SEO Tips for 2024 | SEOZilla",
    "status": "published",
    "featuredImage": {
      "url": "https://storage.blob.core.windows.net/...",
      "proxyUrl": "/api/rest/image-proxy?url=...",
      "prompt": "SEO illustration with modern design"
    },
    "featuredVideoId": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
    "featuredVideo": {
      "id": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
      "videoUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../video",
      "posterUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../poster"
    },
    "keywords": ["SEO", "optimization", "2024"],
    "wordCount": 1523,
    "readingTime": 8,
    "seoScore": 92,
    "readabilityScore": 85,
    "projectId": "proj123",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:00:00Z",
    "publishedAt": "2024-01-15T14:00:00Z",
    "cmsStatus": {
      "ghost": "published",
      "wordpress": null,
      "webflow": "draft"
    },
    "cmsUrls": {
      "ghost": "https://myblog.ghost.io/10-seo-tips-for-2024",
      "wordpress": null,
      "webflow": null
    }
  }
}

Featured Video

Articles can carry a featured video (created with our video tool and starred in the dashboard). When set, article responses include featuredVideoId and a ready-made featuredVideo object; both are null otherwise.

featuredVideo.videoUrl is public — no auth, no expiry. Drop it straight into <video src>; seeking (range requests) is supported. After a video is re-exported the URL serves the new version within ~5 minutes.
featuredVideo.posterUrl is optional — use it as the poster attribute, but handle a 404 gracefully (a small number of older videos have no poster). Posters may be cached by clients for up to 24 hours after a re-export.
The URLs are stable: they always resolve to the video's latest export, so there is nothing to re-fetch or re-sync when a video is updated.

Get Article Count

Get aggregated counts of articles for the authenticated user.

Endpoint

GET /articles/count

Query Parameters

projectId - Filter by project ID (optional)
status - Filter by status: draft, published (optional)

Example Request

curl -X GET "https://www.seozilla.ai/api/rest/articles/count?status=published" \
  -H "Authorization: Bearer sz_YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "total": 45,
    "published": 35,
    "draft": 10
  },
  "filters": {
    "projectId": null,
    "status": "published"
  }
}

Get Project Article Count

Get article counts for a specific project.

Endpoint

GET /projects/:projectId/articles/count

Path Parameters

projectId - The project ID (required)

Query Parameters

status - Filter by status: draft, published (optional)

Example Request

curl -X GET "https://www.seozilla.ai/api/rest/projects/proj123/articles/count" \
  -H "Authorization: Bearer sz_YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "total": 25,
    "published": 18,
    "draft": 7
  },
  "project": {
    "id": "proj123",
    "name": "My SEO Blog",
    "url": "https://example.com"
  }
}

Get Article by Slug

Retrieve a specific article by project ID and slug with full content.

Endpoint

GET /articles/by-slug/:projectId/:slug

Path Parameters

projectId - The project ID (required)
slug - The article slug (required)

Example Request

curl -X GET "https://www.seozilla.ai/api/rest/articles/by-slug/proj123/seo-tips-for-2024" \
  -H "Authorization: Bearer sz_YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "title": "10 SEO Tips for 2024",
    "slug": "10-seo-tips-for-2024",
    "content": "# 10 SEO Tips for 2024\n\nSearch engine optimization...",
    "contentHtml": "<h1>10 SEO Tips for 2024</h1><p>Search engine optimization...</p>",
    "summary": "Discover the latest SEO strategies...",
    "metaDescription": "Learn the top 10 SEO tips for 2024...",
    "seoTitle": "10 SEO Tips for 2024 | SEOZilla",
    "status": "published",
    "featuredImage": {
      "url": "https://storage.blob.core.windows.net/...",
      "proxyUrl": "/api/rest/image-proxy?url=...",
      "prompt": "SEO illustration with modern design"
    },
    "featuredVideoId": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
    "featuredVideo": {
      "id": "6f2c1d9e-6b2a-4a10-9c1e-2f4d8f1a3b7c",
      "videoUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../video",
      "posterUrl": "https://video.seozilla.ai/public/videos/6f2c1d9e-.../poster"
    },
    "keywords": ["SEO", "optimization", "2024"],
    "wordCount": 1523,
    "readingTime": 8,
    "seoScore": 92,
    "readabilityScore": 85,
    "projectId": "proj123",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:00:00Z",
    "publishedAt": "2024-01-15T14:00:00Z",
    "cmsStatus": {
      "ghost": "published",
      "wordpress": null,
      "webflow": "draft"
    },
    "cmsUrls": {
      "ghost": "https://myblog.ghost.io/10-seo-tips-for-2024",
      "wordpress": null,
      "webflow": null
    }
  },
  "redirect": false
}

301 Redirect Support

If an article's slug has changed, this endpoint will return a 301 status with the new slug:

{
  "redirect": true,
  "newSlug": "updated-seo-tips-2024",
  "message": "Article has moved to a new URL"
}

Image Handling

Image Hosting Options

Option 1: Direct URLs (Default)

Images are served directly from Azure Blob Storage. Fast and reliable, but you're responsible for bandwidth costs.

Option 2: Proxy URLs

Use imageHandling=proxy to get proxy URLs that go through our servers. Adds CORS headers and caching.

Option 3: Self-Hosting (Recommended)

Download images and host them on your own CDN. Use the image URL to fetch and store permanently.

API Key Permissions

Permission	Description
`read:articles`	List and view all articles (including drafts)
`read:articles:published`	Access only published articles

Rate Limits

Current Limits

• 100 requests per minute per API key
• 10,000 requests per day per API key
• Response size limited to 10MB