Getting Started

The Eclarion API lets you programmatically manage food specifications: recipes, ingredients, nutritional values, allergens, packaging, and more. This guide walks you through authentication and your first API call.

Base URL

All API requests are made to:

https://api.eclarion.com/v3

Authentication

Most endpoints require authentication via a Bearer token in the Authorization header. You can find your API token in your Eclarion account settings.

Include it in every request:

Authorization: Bearer YOUR_AUTH_TOKEN

Public reference endpoints (allergens, nutrients, etc.) do not require authentication.

Your first API call

Before touching authentication, verify you can reach the API at all. The ping endpoint requires no token:

curl https://api.eclarion.com/v3/ping
{ "status": "ok" }

Next, list your brands. This confirms your authentication is working:

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  https://api.eclarion.com/v3/brands

You should get a JSON response like this:

{
  "brands": [
    {
      "id": 42,
      "name": "My Brand",
      "address": "123 Main St",
      "city": "Amsterdam",
      "country": "NL"
    }
  ]
}

Response format

All responses are JSON. List endpoints wrap results in a plural key:

{ "brands": [...] }
{ "recipes": [...], "meta": { "page": 1, "items": 50, "count": 234, "pages": 5 } }
{ "categories": [...] }

Single resource endpoints wrap in a singular key:

{ "brand": { ... } }
{ "recipe": { ... } }
{ "category": { ... } }

Decimal fields (weights, density, portion sizes, nutritional values) are returned as strings, e.g. "value": "7.5", so no precision is lost in transit. When writing, send them as numbers or strings; both are accepted.

Pagination

The recipes endpoint returns paginated results (max 50 per page). Use the page and items parameters:

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  "https://api.eclarion.com/v3/recipes?page=2&items=25"

The meta object in the response tells you the total count and number of pages. See the List recipes endpoint for all available parameters.

Error handling

Status Meaning
401Missing or invalid authentication token
403Not authorized to access this resource
404Resource not found (or belongs to another account)
422Validation errors (see errors array in response)
429Rate limit exceeded (wait the seconds in the Retry-After header, then retry)

The API allows 100 requests per minute per IP address, of which at most 20 may be image or document uploads. A sync stays well under that with 50 items per page and, for recurring loads, updated_since so you only fetch what changed.

Next steps