Public API

Use this page to integrate with the public JSON API on developers.contentstack.com.

Base URL

• https://developers.contentstack.com

Authentication

• None required.
• All endpoints are read-only.

OpenAPI Contract

• GET /api/openapi.json

This is the canonical machine-readable API description.

Core Endpoints

Unified content search

• GET /api/content

Query parameters:

• types: blogpost,guide,livestream,kickstart,page,person (comma-separated)
• q: free-text query
• subjects: taxonomy subject terms (comma-separated)
• technology: taxonomy technology terms (comma-separated)
• authors: person UIDs (comma-separated)
• limit: 1-50 (default 20)
• offset: >=0 (default 0)

Resource collections

• GET /api/blogposts
• GET /api/guides
• GET /api/livestreams
• GET /api/kickstarts
• GET /api/pages
• GET /api/persons

Resource details

• GET /api/blogposts/{slug}
• GET /api/guides/{...slug}
• GET /api/livestreams/{...slug}
• GET /api/kickstarts/{...slug}
• GET /api/pages/{...slug}
• GET /api/persons/{name}

Filter Semantics

Filters are combined as:

• types: include entries whose type is in the requested set
• q: all query tokens must match (AND)
• subjects: any listed term may match (OR)
• technology: any listed term may match (OR)
• authors: any listed author UID may match (OR)
• Different filter groups are combined with AND

Response Shape

List endpoints return:

{
  "data": [],
  "meta": {
    "total": 0,
    "limit": 20,
    "offset": 0,
    "has_more": false,
    "facets": {
      "content_types": {},
      "subjects": [],
      "technology": [],
      "authors": []
    }
  }
}

Detail endpoints return:

{
  "data": {}
}

Content Body Behavior

• Blog posts, guides, live streams, and kickstarts return markdown in detail responses.
• Pages return structured components JSON (no synthetic markdown).
• Person details return profile data plus grouped authored content.
• API route handlers run in nodejs runtime and are forced dynamic to avoid serverless static optimization edge cases.

Error Format

{
  "error": {
    "code": "bad_request",
    "message": "Invalid 'limit' parameter"
  }
}

Common status codes:

• 400 invalid input
• 404 not found
• 500 unexpected server error

Behavior note:

• The API always returns JSON error responses. Unknown runtime exceptions are normalized to 500 with code: "internal_error" and message "Internal Server Error".
• Public API handlers return native Response objects for Contentstack Launch serverless compatibility.

Quickstart Examples

Search guides/blog posts by technology:

curl "https://developers.contentstack.com/api/content?types=guide,blogpost&subject=ai&limit=10"

Get a person profile and authored content:

curl "https://developers.contentstack.com/api/persons/tim-benniks"

Get full API contract:

curl "https://developers.contentstack.com/api/openapi.json"