API Reference

The CurryCMS API is documented using the OpenAPI 3.0 specification. You can explore the API interactively or download the specification for code generation.

Interactive API Explorer

Use Swagger UI to explore and test API endpoints directly in your browser:

Open API Explorer →

The explorer lets you:
- Browse all available endpoints
- See request/response schemas
- Try out requests with your API token
- View example responses

OpenAPI Specification

Download the OpenAPI specification for use with code generators or API clients:

• OpenAPI 3.0 YAML: /api/v1/openapi.yaml

Code Generation

Use the OpenAPI spec to generate client libraries:

# Using openapi-generator
openapi-generator generate -i openapi.yaml -g ruby -o ./client

# Using swagger-codegen
swagger-codegen generate -i openapi.yaml -l javascript -o ./client

Available Endpoints

Curricula

Content Nodes

User

Response Caching

The API supports HTTP caching via ETags for efficient polling:

# First request - get the ETag
curl -i -H "Authorization: Bearer TOKEN" \
  https://your-domain.com/api/v1/curricula/123

# Response includes: ETag: "abc123"

# Subsequent request - use If-None-Match
curl -i -H "Authorization: Bearer TOKEN" \
  -H "If-None-Match: \"abc123\"" \
  https://your-domain.com/api/v1/curricula/123

# Returns 304 Not Modified if unchanged (no body, saves bandwidth)

Lazy Loading Pattern

Content nodes use a lazy-loading pattern for efficient tree traversal:

1. Each node includes a has_children boolean
2. Children are returned as direct descendants only (not full subtree)
3. Traverse deeper by fetching child nodes as needed

// Recursive tree loading example
async function loadNode(nodeId) {
  const response = await fetch(`/api/v1/content_nodes/${nodeId}`, {
    headers: { 'Authorization': 'Bearer TOKEN' }
  });
  const { data } = await response.json();

  // Children are included in the response
  for (const child of data.relationships.children.data) {
    if (child.attributes.has_children) {
      // Fetch deeper children on demand
      await loadNode(child.id);
    }
  }
}

Error Codes