API Documentation

AgentCMS provides a RESTful API for managing content programmatically. All endpoints accept and return JSON.

Quick Example

# Create a blog post
curl -X POST https://agentcms-api.rckflr.workers.dev/v1/content/posts \
  -H "X-API-Key: acms_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "slug": "my-first-post",
    "fields": {
      "excerpt": "A quick intro...",
      "body": "Full content here..."
    }
  }'

Authentication

All API requests (except public endpoints) require authentication via API key. Include your key in the X-API-Key header.

curl https://agentcms-api.rckflr.workers.dev/v1/types \
  -H "X-API-Key: acms_live_your_api_key_here"

Alternatively, use the Authorization header with Bearer token:

curl https://agentcms-api.rckflr.workers.dev/v1/types \
  -H "Authorization: Bearer acms_live_your_api_key_here"

Error Handling

The API uses standard HTTP status codes. Errors return a JSON object with an error field.

// Error response example
{
  "error": "Content type not found"
}

List all content types.

Response

{
  "types": [
    {
      "id": "ct_abc123",
      "name": "Blog Posts",
      "slug": "posts",
      "description": "Blog articles",
      "fields": [
        { "name": "excerpt", "type": "text", "required": false },
        { "name": "body", "type": "text", "required": true }
      ],
      "created_at": "2024-12-28T10:00:00Z"
    }
  ]
}

Create a new content type.

Request Body

{
  "name": "Products",
  "slug": "products",
  "description": "E-commerce products",
  "fields": [
    { "name": "price", "type": "number", "required": true },
    { "name": "sku", "type": "string", "required": true },
    { "name": "description", "type": "text", "required": false },
    { "name": "in_stock", "type": "boolean", "required": false }
  ]
}

Field Types

• string - Short text (max 500 chars)
• text - Long text (unlimited)
• number - Integer or decimal
• boolean - true/false
• date - ISO 8601 date string
• url - Valid URL
• email - Valid email address
• json - Arbitrary JSON object

Get a single content type by slug.

Update a content type. Only provided fields will be updated.

Delete a content type and all its content. This action is irreversible.

List content items of a specific type.

Query Parameters

• status - Filter by status: draft, published, private, trash
• limit - Max items to return (default: 20, max: 100)
• offset - Items to skip for pagination

# Get published posts, page 2
curl "https://agentcms-api.rckflr.workers.dev/v1/content/posts?status=published&limit=10&offset=10" \
  -H "X-API-Key: acms_live_xxx"

Create a new content item.

curl -X POST https://agentcms-api.rckflr.workers.dev/v1/content/posts \
  -H "X-API-Key: acms_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with AgentCMS",
    "slug": "getting-started",
    "fields": {
      "excerpt": "Learn how to use AgentCMS...",
      "body": "Full article content...",
      "author": "John Doe"
    }
  }'

Get a single content item by slug.

{
  "id": "cnt_xyz789",
  "type_slug": "posts",
  "title": "Getting Started",
  "slug": "getting-started",
  "status": "published",
  "fields": {
    "excerpt": "Learn how to...",
    "body": "Full content..."
  },
  "taxonomy_terms": ["term_cat1", "term_tag2"],
  "created_at": "2024-12-28T10:00:00Z",
  "updated_at": "2024-12-28T12:00:00Z",
  "published_at": "2024-12-28T12:00:00Z"
}

Update a content item. Only provided fields are updated.

curl -X PUT https://agentcms-api.rckflr.workers.dev/v1/content/posts/getting-started \
  -H "X-API-Key: acms_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "fields": {
      "excerpt": "New excerpt..."
    }
  }'

Delete a content item permanently.

Publish a content item. Published content is visible via the public API.

# Publish
curl -X POST https://agentcms-api.rckflr.workers.dev/v1/content/posts/my-post/publish \
  -H "X-API-Key: acms_live_xxx"

Unpublish a content item (sets status to draft).

List all taxonomies with their terms.

{
  "taxonomies": [
    {
      "id": "tax_abc",
      "name": "Categories",
      "slug": "categories",
      "hierarchical": true,
      "terms": [
        { "id": "term_1", "name": "Tech", "slug": "tech" },
        { "id": "term_2", "name": "News", "slug": "news" }
      ]
    }
  ]
}

Create a new taxonomy.

{
  "name": "Tags",
  "slug": "tags",
  "hierarchical": false
}

Create a new term within a taxonomy.

{
  "name": "JavaScript",
  "slug": "javascript",
  "parent_id": "term_tech"  // Optional, for hierarchical taxonomies
}

Assign taxonomy terms to a content item.

{
  "term_ids": ["term_1", "term_2", "term_3"]
}

Remove taxonomy terms from a content item.

Search across all content.

Query Parameters

• q - Search query (required)
• type - Limit to specific content type
• status - Filter by status
• limit - Max results (default: 20)

curl "https://agentcms-api.rckflr.workers.dev/v1/search?q=javascript&type=posts" \
  -H "X-API-Key: acms_live_xxx"

Get statistics about your CMS.

{
  "content_types": 3,
  "total_content": 42,
  "by_type": {
    "posts": 25,
    "products": 15,
    "pages": 2
  },
  "by_status": {
    "published": 30,
    "draft": 10,
    "private": 2
  },
  "taxonomies": 2,
  "total_terms": 15
}

List published content. No authentication required. Use this for your frontend/website.

# No API key needed!
curl https://agentcms-api.rckflr.workers.dev/public/posts

Get a single published content item. No authentication required.

MCP Server Setup

Connect AI assistants like Claude or ChatGPT to AgentCMS using the Model Context Protocol.

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agentcms": {
      "url": "https://agentcms-mcp.rckflr.workers.dev"
    }
  }
}

Authentication Flow

The MCP server uses OAuth 2.1 with PKCE. When you first connect:

1. The AI client will open a browser for authentication
2. Enter your email to receive a verification code
3. Enter the 6-digit code to complete authentication
4. The session is saved - no need to re-authenticate

MCP Tools

Once connected, your AI assistant can use these 15 tools:

Example Prompts