API Reference

The ACMS dev server exposes a REST API on port 3001 (by default) for managing content fields programmatically. This API is used by the client library, the dashboard, and can be used by custom tools.

Base URL

http://localhost:3001/api

Endpoints

Get Full Schema

Retrieve the complete schema including fields, groups, and metadata.

GET /api/schema

Response:

{
  "fields": {
    "hero": {
      "title": "Welcome to ACMS",
      "subtitle": "Schema-less content management"
    },
    "contact": {
      "email": "hello@example.com"
    }
  },
  "groups": ["hero", "contact"],
  "meta": {
    "hero.title": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    },
    "hero.subtitle": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    },
    "contact.email": {
      "type": "string",
      "lastAccessed": "2025-01-15T10:30:00.000Z"
    }
  }
}

Get Content Only

Retrieve content values without metadata. This is what the client library uses to fetch content.

GET /api/content

Response:

{
  "hero": {
    "title": "Welcome to ACMS",
    "subtitle": "Schema-less content management"
  },
  "contact": {
    "email": "hello@example.com"
  }
}

Update Field Value

Set or update a field’s value.

POST /api/field

Request body:

{
  "path": "hero.title",
  "value": "Welcome to My Site"
}

Response:

{
  "success": true
}

Register Field

Register a new field (used by the client proxy during development).

POST /api/register

Request body:

{
  "path": "hero.title"
}

Response:

{
  "success": true
}

If the field already exists, the endpoint returns success without modifying the value.

Update Field Metadata

Update metadata for a field (type, label, default value, etc.).

PATCH /api/field/:path/meta

Example:

curl -X PATCH http://localhost:3001/api/field/hero.title/meta \
  -H "Content-Type: application/json" \
  -d '{"type": "text"}'

Request body:

{
  "type": "text",
  "label": "Hero Title",
  "defaultValue": "Default Title"
}

Response:

{
  "success": true
}

Delete Field

Remove a field from the schema.

DELETE /api/field/:path

Example:

curl -X DELETE http://localhost:3001/api/field/hero.subtitle

Response:

{
  "success": true
}

Create New Field

Create a new field with a specified type.

POST /api/field/new

Request body:

{
  "path": "hero.ctaText",
  "type": "string",
  "value": "Learn More"
}

Response:

{
  "success": true
}

Push Array Item

Add an item to an array field.

POST /api/array/:path/push

Example:

curl -X POST http://localhost:3001/api/array/features/push \
  -H "Content-Type: application/json" \
  -d '{"value": "New Feature"}'

Request body:

{
  "value": "New Feature"
}

Response:

{
  "success": true
}

Remove Array Item

Remove an item from an array by index.

DELETE /api/array/:path/:index

Example:

curl -X DELETE http://localhost:3001/api/array/features/2

Response:

{
  "success": true
}

Reorder Array Items

Change the order of items in an array.

PATCH /api/array/:path/reorder

Request body:

{
  "from": 0,
  "to": 2
}

Response:

{
  "success": true
}

Server-Sent Events

Subscribe to real-time schema updates.

GET /api/events

This endpoint returns an SSE stream. The server sends events whenever acms.json is modified:

event: schema-update
data: {"type": "schema-update"}

Example usage in JavaScript:

const eventSource = new EventSource('http://localhost:3001/api/events');

eventSource.addEventListener('schema-update', (event) => {
  console.log('Schema updated, refetching...');
  // Refetch content from /api/content
});

Error Responses

All endpoints return standard error responses:

{
  "error": "Field not found",
  "status": 404
}

Common HTTP status codes:

Status	Meaning
200	Success
400	Bad request (invalid path, missing body)
404	Field not found
409	Conflict (reserved field name)
500	Internal server error

CORS

The dev server enables CORS for all origins, allowing requests from any frontend application running on any port during development.

Next Steps

• Set up the Dashboard for visual editing
• Learn about TypeScript integration
• Explore Framework Guides for your stack