Content API

Welcome to the ElmapiCMS Content API. Our API is designed to be a simple, predictable, and powerful interface for managing your content. It follows RESTful conventions and uses standard HTTP features, including methods and status codes. All API responses are returned in JSON format.

Authentication

The ElmapiCMS Content API is project-based. Every request to the API must be scoped to a specific project. You can do this by including the project-id header with your project's unique ID.

project-id: YOUR_PROJECT_UUID

Public vs. Private APIs

Projects can have either a public or a private API, which affects how you authenticate.

• Public API: If a project's API is public, you only need to provide the project-id header to access its content.
• Private API: For private projects, you must include an API token with your request. This is done by sending a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

You can generate API tokens from your project's settings page.

Token Abilities

API tokens can be assigned specific abilities to control what actions they can perform:

The admin ability is required for schema management endpoints such as creating collections and fields. See the Collections and Fields sections for details.

Rate Limiting

The API is rate-limited. You can make up to 60 requests per minute. If you exceed this limit, you will receive a 429 Too Many Requests response.

To change the rate limit, open routes/api.php and change the throttle parameter.

Route::middleware(['project', 'throttle:60,1'])->group(function () {
    // ...
});

For more information you can visit the Laravel documentation.

Core Concepts

The API is built around three core concepts:

• Collections: These are the blueprints for your content. You can think of them as defining the structure or schema for different types of content (e.g., "Blog Posts", "Products", "Events"). You can read more about collections here.
• Content: These are the individual entries or records that conform to a collection's schema. For example, a single blog post is a piece of content. You can read more about content here.
• Assets: These are your media files, such as images, videos, and documents. You can upload and manage assets independently and link them to your content entries. You can read more about assets here.

Status Codes

The API uses the following response codes:

• 200 OK: The request was successful.
• 400 Bad Request: The request was invalid.
• 401 Unauthorized: The request was unauthorized.
• 403 Forbidden: The request was forbidden.
• 404 Not Found: The requested resource was not found.
• 422 Unprocessable Entity: The request was valid, but the server was unable to process it (e.g. validation errors).
• 429 Too Many Requests: The request was rate-limited.
• 500 Internal Server Error: The server encountered an error.

Error Handling

The API returns errors in the following format:

{
    "message": "The project was not found."
}

JavaScript SDK

For a more convenient way to interact with the ElmapiCMS API, you can use our official JavaScript SDK. The SDK provides a simple, type-safe interface for making API requests and handles authentication automatically.

Installation

Install the SDK using npm:

npm install @elmapicms/js-sdk

Or using yarn:

yarn add @elmapicms/js-sdk

Package Information

The SDK is available on npm: @elmapicms/js-sdk

For detailed usage instructions and API reference, please refer to the package documentation on npm.