Skip to content
EmDash

REST API Reference

EmDash exposes a REST API at /_emdash/api/ for content management, media uploads, and schema operations.

Authentication

Section titled “Authentication”

API requests require authentication via Bearer token:

Authorization: Bearer <token>

Generate tokens through the admin interface or programmatically.

Response Format

Section titled “Response Format”

All responses follow a consistent format:

// Success
{
  "success": true,
  "data": { ... }
}


// Error
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  }
}

Content Endpoints

Section titled “Content Endpoints”

List Content

Section titled “List Content”
GET /_emdash/api/content/:collection

Parameters

Section titled “Parameters”
ParameterTypeDescription
collectionstringCollection slug (path)
cursorstringPagination cursor (query)
limitnumberItems per page (query, default: 50)
statusstringFilter by status (query)
orderBystringField to sort by (query)
orderstringSort direction: asc or desc (query)

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "type": "posts",
        "slug": "hello-world",
        "data": { "title": "Hello World", ... },
        "status": "published",
        "createdAt": "2025-01-24T12:00:00Z",
        "updatedAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Get Content

Section titled “Get Content”
GET /_emdash/api/content/:collection/:id

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "item": {
      "id": "01HXK5MZSN...",
      "type": "posts",
      "slug": "hello-world",
      "data": { "title": "Hello World", ... },
      "status": "published",
      "createdAt": "2025-01-24T12:00:00Z",
      "updatedAt": "2025-01-24T12:00:00Z"
    }
  }
}

Create Content

Section titled “Create Content”
POST /_emdash/api/content/:collection
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "data": {
    "title": "New Post",
    "content": [...]
  },
  "slug": "new-post",
  "status": "draft"
}

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "item": { ... }
  }
}

Update Content

Section titled “Update Content”
PATCH /_emdash/api/content/:collection/:id
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "data": {
    "title": "Updated Title"
  },
  "status": "published"
}

Delete Content

Section titled “Delete Content”
DELETE /_emdash/api/content/:collection/:id

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "success": true
  }
}

Media Endpoints

Section titled “Media Endpoints”

List Media

Section titled “List Media”
GET /_emdash/api/media

Parameters

Section titled “Parameters”
ParameterTypeDescription
cursorstringPagination cursor
limitnumberItems per page (default: 20)
mimeTypestringFilter by MIME type prefix

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "filename": "photo.jpg",
        "mimeType": "image/jpeg",
        "size": 102400,
        "width": 1920,
        "height": 1080,
        "url": "https://cdn.example.com/photo.jpg",
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Get Media

Section titled “Get Media”
GET /_emdash/api/media/:id

Create Media

Section titled “Create Media”
POST /_emdash/api/media
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "filename": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 102400,
  "width": 1920,
  "height": 1080,
  "storageKey": "uploads/photo.jpg"
}

Update Media

Section titled “Update Media”
PATCH /_emdash/api/media/:id
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "alt": "Photo description",
  "caption": "Photo caption"
}

Delete Media

Section titled “Delete Media”
DELETE /_emdash/api/media/:id

Get Media File

Section titled “Get Media File”
GET /_emdash/api/media/file/:key

Serves the actual file content. For local storage only.

Revision Endpoints

Section titled “Revision Endpoints”

List Revisions

Section titled “List Revisions”
GET /_emdash/api/content/:collection/:entryId/revisions

Parameters

Section titled “Parameters”
ParameterTypeDescription
limitnumberMax revisions to return (default: 50)

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "collection": "posts",
        "entryId": "01HXK5MZSN...",
        "data": { ... },
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "total": 5
  }
}

Get Revision

Section titled “Get Revision”
GET /_emdash/api/revisions/:revisionId

Restore Revision

Section titled “Restore Revision”
POST /_emdash/api/revisions/:revisionId/restore

Restores content to this revision’s state and creates a new revision.

Schema Endpoints

Section titled “Schema Endpoints”

List Collections

Section titled “List Collections”
GET /_emdash/api/schema/collections

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "slug": "posts",
        "label": "Posts",
        "labelSingular": "Post",
        "supports": ["drafts", "revisions", "preview"]
      }
    ]
  }
}

Get Collection

Section titled “Get Collection”
GET /_emdash/api/schema/collections/:slug

Parameters

Section titled “Parameters”
ParameterTypeDescription
includeFieldsbooleanInclude field definitions (query)

Create Collection

Section titled “Create Collection”
POST /_emdash/api/schema/collections
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "slug": "products",
  "label": "Products",
  "labelSingular": "Product",
  "description": "Product catalog",
  "supports": ["drafts", "revisions"]
}

Update Collection

Section titled “Update Collection”
PATCH /_emdash/api/schema/collections/:slug
Content-Type: application/json

Delete Collection

Section titled “Delete Collection”
DELETE /_emdash/api/schema/collections/:slug

Parameters

Section titled “Parameters”
ParameterTypeDescription
forcebooleanDelete even if collection has content (query)

List Fields

Section titled “List Fields”
GET /_emdash/api/schema/collections/:slug/fields

Create Field

Section titled “Create Field”
POST /_emdash/api/schema/collections/:slug/fields
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "slug": "price",
  "label": "Price",
  "type": "number",
  "required": true,
  "validation": {
    "min": 0
  }
}

Update Field

Section titled “Update Field”
PATCH /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
Content-Type: application/json

Delete Field

Section titled “Delete Field”
DELETE /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug

Reorder Fields

Section titled “Reorder Fields”
POST /_emdash/api/schema/collections/:slug/fields/reorder
Content-Type: application/json

Request Body

Section titled “Request Body”
{
  "fieldSlugs": ["title", "content", "author", "publishedAt"]
}

Schema Export

Section titled “Schema Export”

Export Schema (JSON)

Section titled “Export Schema (JSON)”
GET /_emdash/api/schema
Accept: application/json

Export Schema (TypeScript)

Section titled “Export Schema (TypeScript)”
GET /_emdash/api/schema?format=typescript
Accept: text/typescript

Returns TypeScript interfaces for all collections.

Plugin Endpoints

Section titled “Plugin Endpoints”

List Plugins

Section titled “List Plugins”
GET /_emdash/api/plugins

Get Plugin

Section titled “Get Plugin”
GET /_emdash/api/plugins/:pluginId

Enable Plugin

Section titled “Enable Plugin”
POST /_emdash/api/plugins/:pluginId/enable

Disable Plugin

Section titled “Disable Plugin”
POST /_emdash/api/plugins/:pluginId/disable

Error Codes

Section titled “Error Codes”
CodeHTTP StatusDescription
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid input data
UNAUTHORIZED401Missing or invalid token
FORBIDDEN403Insufficient permissions
CONTENT_LIST_ERROR500Failed to list content
CONTENT_CREATE_ERROR500Failed to create content
CONTENT_UPDATE_ERROR500Failed to update content
CONTENT_DELETE_ERROR500Failed to delete content
MEDIA_LIST_ERROR500Failed to list media
MEDIA_CREATE_ERROR500Failed to create media
SCHEMA_ERROR400Schema operation failed
DUPLICATE_SLUG409Slug already exists
RESERVED_SLUG400Slug is reserved

Search Endpoints

Section titled “Search Endpoints”
Section titled “Global Search”
GET /_emdash/api/search?q=hello+world

Parameters

Section titled “Parameters”
ParameterTypeDescription
qstringSearch query (required)
collectionsstringComma-separated collection slugs
statusstringFilter by status (default: published)
limitnumberMax results (default: 20)
cursorstringPagination cursor

Response

Section titled “Response”
{
  "results": [
    {
      "collection": "posts",
      "id": "01HXK5MZSN...",
      "slug": "hello-world",
      "title": "Hello World",
      "snippet": "...this is a <mark>hello</mark> <mark>world</mark> example...",
      "score": 0.95
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ"
}

Search Suggestions

Section titled “Search Suggestions”
GET /_emdash/api/search/suggest?q=hel&limit=5

Returns prefix-matched titles for autocomplete.

Rebuild Search Index

Section titled “Rebuild Search Index”
POST /_emdash/api/search/rebuild

Rebuild FTS index for all or specific collections.

Search Stats

Section titled “Search Stats”
GET /_emdash/api/search/stats

Returns indexed document counts per collection.

Section Endpoints

Section titled “Section Endpoints”

List Sections

Section titled “List Sections”
GET /_emdash/api/sections
GET /_emdash/api/sections?source=theme
GET /_emdash/api/sections?search=newsletter

Get Section

Section titled “Get Section”
GET /_emdash/api/sections/:slug

Create Section

Section titled “Create Section”
POST /_emdash/api/sections
Content-Type: application/json


{
  "slug": "my-section",
  "title": "My Section",
  "keywords": ["keyword1"],
  "content": [...]
}

Update Section

Section titled “Update Section”
PUT /_emdash/api/sections/:slug

Delete Section

Section titled “Delete Section”
DELETE /_emdash/api/sections/:slug

Settings Endpoints

Section titled “Settings Endpoints”

Get All Settings

Section titled “Get All Settings”
GET /_emdash/api/settings

Update Settings

Section titled “Update Settings”
PUT /_emdash/api/settings
Content-Type: application/json


{
  "siteTitle": "My Site",
  "tagline": "A great site",
  "postsPerPage": 10
}
Section titled “Menu Endpoints”

List Menus

Section titled “List Menus”
GET /_emdash/api/menus

Get Menu

Section titled “Get Menu”
GET /_emdash/api/menus/:name

Create Menu

Section titled “Create Menu”
POST /_emdash/api/menus
Content-Type: application/json


{
  "name": "footer",
  "label": "Footer Navigation"
}

Update Menu

Section titled “Update Menu”
PUT /_emdash/api/menus/:name

Delete Menu

Section titled “Delete Menu”
DELETE /_emdash/api/menus/:name

Add Menu Item

Section titled “Add Menu Item”
POST /_emdash/api/menus/:name/items
Content-Type: application/json


{
  "type": "page",
  "referenceCollection": "pages",
  "referenceId": "page_about",
  "label": "About Us"
}

Reorder Menu Items

Section titled “Reorder Menu Items”
POST /_emdash/api/menus/:name/reorder
Content-Type: application/json


{
  "items": [
    { "id": "item_1", "parentId": null, "sortOrder": 0 },
    { "id": "item_2", "parentId": null, "sortOrder": 1 },
    { "id": "item_3", "parentId": "item_2", "sortOrder": 0 }
  ]
}

Taxonomy Endpoints

Section titled “Taxonomy Endpoints”

List Taxonomy Definitions

Section titled “List Taxonomy Definitions”
GET /_emdash/api/taxonomies

Create Taxonomy

Section titled “Create Taxonomy”
POST /_emdash/api/taxonomies
Content-Type: application/json


{
  "name": "genre",
  "label": "Genres",
  "labelSingular": "Genre",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

List Terms

Section titled “List Terms”
GET /_emdash/api/taxonomies/:name/terms

Create Term

Section titled “Create Term”
POST /_emdash/api/taxonomies/:name/terms
Content-Type: application/json


{
  "slug": "tutorials",
  "label": "Tutorials",
  "parentId": "term_abc",
  "description": "How-to guides"
}

Update Term

Section titled “Update Term”
PUT /_emdash/api/taxonomies/:name/terms/:slug

Delete Term

Section titled “Delete Term”
DELETE /_emdash/api/taxonomies/:name/terms/:slug

Set Entry Terms

Section titled “Set Entry Terms”
POST /_emdash/api/content/:collection/:id/terms/:taxonomy
Content-Type: application/json


{
  "termIds": ["term_news", "term_featured"]
}

Widget Area Endpoints

Section titled “Widget Area Endpoints”

List Widget Areas

Section titled “List Widget Areas”
GET /_emdash/api/widget-areas

Get Widget Area

Section titled “Get Widget Area”
GET /_emdash/api/widget-areas/:name

Create Widget Area

Section titled “Create Widget Area”
POST /_emdash/api/widget-areas
Content-Type: application/json


{
  "name": "sidebar",
  "label": "Main Sidebar",
  "description": "Appears on posts"
}

Delete Widget Area

Section titled “Delete Widget Area”
DELETE /_emdash/api/widget-areas/:name

Add Widget

Section titled “Add Widget”
POST /_emdash/api/widget-areas/:name/widgets
Content-Type: application/json


{
  "type": "content",
  "title": "About",
  "content": [...]
}

Update Widget

Section titled “Update Widget”
PUT /_emdash/api/widget-areas/:name/widgets/:id

Delete Widget

Section titled “Delete Widget”
DELETE /_emdash/api/widget-areas/:name/widgets/:id

Reorder Widgets

Section titled “Reorder Widgets”
POST /_emdash/api/widget-areas/:name/reorder
Content-Type: application/json


{
  "widgetIds": ["widget_1", "widget_2", "widget_3"]
}

User Management Endpoints

Section titled “User Management Endpoints”

List Users

Section titled “List Users”
GET /_emdash/api/admin/users
GET /_emdash/api/admin/users?role=40
GET /_emdash/api/admin/users?search=john

Get User

Section titled “Get User”
GET /_emdash/api/admin/users/:id

Update User

Section titled “Update User”
PATCH /_emdash/api/admin/users/:id
Content-Type: application/json


{
  "name": "John Doe",
  "role": 40
}

Enable User

Section titled “Enable User”
POST /_emdash/api/admin/users/:id/enable

Disable User

Section titled “Disable User”
POST /_emdash/api/admin/users/:id/disable

Authentication Endpoints

Section titled “Authentication Endpoints”

Setup Status

Section titled “Setup Status”
GET /_emdash/api/setup/status

Returns whether setup is complete and if users exist.

Passkey Login

Section titled “Passkey Login”
POST /_emdash/api/auth/passkey/options

Get WebAuthn authentication options.

POST /_emdash/api/auth/passkey/verify
Content-Type: application/json


{
  "id": "credential-id",
  "rawId": "...",
  "response": {...},
  "type": "public-key"
}

Verify passkey and create session.

Section titled “Magic Link”
POST /_emdash/api/auth/magic-link/send
Content-Type: application/json


{
  "email": "user@example.com"
}
GET /_emdash/api/auth/magic-link/verify?token=xxx

Logout

Section titled “Logout”
POST /_emdash/api/auth/logout

Current User

Section titled “Current User”
GET /_emdash/api/auth/me

Invite User

Section titled “Invite User”
POST /_emdash/api/auth/invite
Content-Type: application/json


{
  "email": "newuser@example.com",
  "role": 30
}

Passkey Management

Section titled “Passkey Management”
GET /_emdash/api/auth/passkey

List user’s passkeys.

POST /_emdash/api/auth/passkey/register/options
POST /_emdash/api/auth/passkey/register/verify

Register new passkey.

PATCH /_emdash/api/auth/passkey/:id
Content-Type: application/json


{
  "name": "MacBook Pro"
}

Rename passkey.

DELETE /_emdash/api/auth/passkey/:id

Delete passkey.

Import Endpoints

Section titled “Import Endpoints”

Analyze WordPress Export

Section titled “Analyze WordPress Export”
POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data


file: <WXR file>

Execute WordPress Import

Section titled “Execute WordPress Import”
POST /_emdash/api/import/wordpress/execute
Content-Type: application/json


{
  "analysisId": "...",
  "options": {
    "includeMedia": true,
    "includeTaxonomies": true,
    "includeMenus": true
  }
}

Rate Limiting

Section titled “Rate Limiting”

API endpoints may be rate-limited based on deployment configuration. When rate-limited, responses include:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

CORS

Section titled “CORS”

The API supports CORS for browser requests. Configure allowed origins in your deployment.