Skip to content
On this pageAuthentication: API Tokens
  1. Authentication: API Tokens
  2. Key Endpoints
  3. Pagination and Filtering
  4. REST vs Internal API: When to Use Which
  5. Response Format

EmDash REST API: External Access to Your Content

Ben 3 min read

EmDash is primarily designed to power Astro pages via its TypeScript content API. But there are legitimate reasons to reach content from outside that context — a mobile app, a marketing tool, a data pipeline, or a separate frontend. For those cases, EmDash exposes a REST API.

This article covers the authentication model, the available endpoints, response shapes, and the important decision of when to use REST versus the internal TypeScript API.

Authentication: API Tokens

The REST API uses token-based authentication. Generate a token in the EmDash admin panel under Settings > API Tokens. Tokens are scoped — you can create read-only tokens for external consumers and keep write-capable tokens limited to trusted integrations.

Pass the token in the Authorization header on every request:

# List entries from the 'posts' collection
curl https://yoursite.com/_emdash/api/collections/posts/entries \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get a single entry by slug
curl https://yoursite.com/_emdash/api/collections/posts/entries/my-post-slug \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Search across collections
curl "https://yoursite.com/_emdash/api/search?q=your+query&collections=posts,docs" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Key Endpoints

All API routes are under /_emdash/api/. The table below covers the most commonly used endpoints for reading published content.

MethodEndpointDescription
GET/_emdash/api/collections/:collection/entriesList published entries. Supports limit, cursor, orderBy query params.
GET/_emdash/api/collections/:collection/entries/:slugGet a single published entry by slug.
GET/_emdash/api/searchFull-text search. Params: q, collections (comma-separated), limit.
GET/_emdash/api/taxonomies/:taxonomy/termsList all terms in a taxonomy (e.g. category, tag).
GET/_emdash/api/settingsRead public site settings (title, description, logo).

Pagination and Filtering

List endpoints use cursor-based pagination. The response includes a nextCursor field when more results are available. Pass it as the cursor query parameter on the next request. The limit parameter defaults to 20 and caps at 100.

REST vs Internal API: When to Use Which

If you're building Astro pages in your EmDash site, always use getEmDashCollection() and getEmDashEntry() from emdash. These query the database directly — no HTTP overhead, full TypeScript types, and cache hint support built in.

Use the REST API only when the consumer lives outside your Astro process: a React Native app, a Python script, a Zapier integration, or a separate headless frontend consuming your site as a backend.

For Astro pages, the internal TypeScript API is always the right choice. REST is for when your consumer lives outside the Astro process entirely.

Response Format

All responses are JSON. List endpoints return { entries, nextCursor }. Single-entry endpoints return the entry object directly. Error responses use standard HTTP status codes (401 for missing/invalid token, 404 for not found, 422 for validation errors) with a JSON body containing a message field.

The REST API gives you a clean, token-authenticated interface to your EmDash content from any HTTP client. For the next level of integration — using EmDash as a content source for an AI agent or automated workflow — the MCP server is worth exploring.

Read: EmDash MCP Server