Platform API & AI

This site is built to be AI-native. Every piece of content is accessible as structured JSON, markdown, or via an MCP server — no scraping or authentication required.

Discovery Endpoints

These endpoints help LLMs, agents, and crawlers discover what the site offers and how to interact with it.

llms.txt

• GET /llms.txt
• Content-Type: text/plain

A plain-text file following the llms.txt standard. It tells LLMs what the site is about, what content types are available, how to access content as markdown, and where to find the API and MCP server.

agents.md

• GET /agents.md
• Content-Type: text/markdown

A detailed agent policy document. Includes allowed actions (read-only), available API endpoints, MCP server tools, content access methods, and a dynamically generated content index with every piece of content on the site.

robots.txt

• GET /robots.txt
• Content-Type: text/plain

Standard crawl policy. Allows all paths except /preview and /api/preview. References /sitemap.xml.

Sitemaps

XML Sitemap

• GET /sitemap.xml

Standard XML sitemap auto-generated by Next.js. Includes all published pages, blog posts, guides, livestreams, and kickstarts with lastModified, changeFrequency, and priority fields.

Markdown Sitemap

• GET /sitemap.md
• Content-Type: text/markdown

A human- and LLM-readable sitemap grouped by content type. Includes instructions for accessing content as markdown, MCP server info, API reference, and a full listing of all guides (with chapter counts), blog posts, livestreams, pages, and people.

MCP Server

The site runs a Model Context Protocol server that allows AI agents to search and read content through structured tool calls.

Connection

• Streamable HTTP: https://developers.contentstack.com/api/mcp
• SSE (fallback): https://developers.contentstack.com/api/sse
• Authentication: None required

Tools

The MCP server exposes four tools:

content_search

Full-text search across all content with optional filters.

Parameters:

• query (string) — Search query
• types (array) — Filter by content type: blog, guide, livestream, kickstart
• subjects (array) — Filter by subject taxonomy
• technology (array) — Filter by technology taxonomy
• author (string) — Filter by author
• limit (number) — Results per page
• offset (number) — Pagination offset

Returns: Ranked results array, total count, and facets (content types, subjects, technology, authors).

content_get

Fetch the full content of any page as markdown by its URL path.

Parameters:

• url (string) — Path starting with / (e.g., /blog/my-post)

Returns: Title, type, URL, markdown body, and metadata (description, authors, subjects, created_at, updated_at, canonical URL).

Supports blog posts, guides (including individual chapters), livestreams, kickstarts, and person pages.

people_get_profile

Get a person's full profile and all their authored content.

Parameters:

• name_or_slug (string) — e.g., tim-benniks or /person/tim-benniks

Returns: Name, job title, bio (markdown), URL, image, and content arrays (blogs, guides, livestreams with title, URL, created_at).

people_list

List all people on the site.

Parameters: None

Returns: Array of people with name, job title, URL, and image.

Markdown Content Access

All content on the site can be accessed as clean markdown in two ways:

Accept Header

Send an Accept: text/markdown header to any content URL:

curl -H "Accept: text/markdown" https://developers.contentstack.com/blog/my-post

.md URL Suffix

Append .md to any content URL:

curl https://developers.contentstack.com/blog/my-post.md

Both methods return the full content as markdown with metadata.

Dedicated Markdown Routes

The site also serves markdown at explicit /md/ paths:

• /md/blog/{slug} — Blog posts
• /md/guides/{...slug} — Guides and chapters
• /md/livestreams/{...slug} — Livestreams
• /md/kickstarts/{...slug} — Kickstarts

Public JSON API

All content is available as structured JSON through a RESTful API. No authentication required.

Base URL

• https://developers.contentstack.com

OpenAPI Specification

• GET /api/openapi.json
• OpenAPI Version: 3.1.0

The canonical machine-readable API description. Documents all endpoints with request/response schemas, parameters, and examples.

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

The API always returns JSON error responses. Unknown runtime exceptions are normalized to 500 with code: "internal_error" and message "Internal Server Error".

Quickstart Examples

Search guides and blog posts by subject:

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 the full API contract:

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

Caching

All endpoints are cached with a 1-hour TTL (public, max-age=3600). The sitemap uses ISR with hourly revalidation. Content is always fresh within an hour of publishing.

Summary