Location & Organization Management

The Location & Organization domain is the foundation of the Chataigne API. An organization groups one or more locations. Each location carries its own configuration — currency, address, opening hours, delivery rules, AI instructions — plus any special closings for holidays or one-off events. Your API key determines which surface you can reach and which workspace you act on, so understanding this mapping is the first step to integrating.

All requests go to the base URL https://server.chataigne.ai. Every resource is identified by an opaque, prefixed id (for example org_…, loc_…, scl_…) and exposes object, created_at, and updated_at (ISO 8601 UTC).

The domain model

organization (org_…)
└── locations (loc_…)
    ├── order_settings        — auto-accept, prep time
    ├── opening_hours         — delivery & pickup schedules
    ├── delivery_settings     — fees, radius, min/max order
    ├── acceptance_settings   — online / busy / paused
    ├── ai_instructions       — chatbot guidance
    └── special_closings (scl_…) — holidays, one-off closures

Organizations

The top-level container. Holds location_ids and active_location_ids.

Locations

A single restaurant: currency, country, timezone, language, address.

Settings

Per-location sub-resources: orders, hours, delivery, acceptance, AI.

Special closings

Time-bounded closures with an optional reason.

Organizations contain locations

An organization is the workspace boundary. It tracks the locations it owns and which of them are currently active.

string

Unique identifier, prefixed org_….

object

string

Always "organization".

name

string

Display name of the organization.

location_ids

string[]

All locations owned by the organization (loc_…).

active_location_ids

string[]

Subset of location_ids that are currently active.

created_at

string

Creation timestamp (ISO 8601 UTC).

updated_at

string

Last-update timestamp (ISO 8601 UTC).

By default an organization references its locations by id. Use expansion to inline the full location objects in a single call.

curl https://server.chataigne.ai/v1/organizations/org_8tKx2qP4mN \
  -H "x-api-key: ch_org_live_4f9c2a..." \
  --data-urlencode "expand[]=locations" -G

Response

{
  "id": "org_8tKx2qP4mN",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_a1B2c3D4", "loc_e5F6g7H8"],
  "active_location_ids": ["loc_a1B2c3D4"],
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-05-20T14:02:11Z"
}

Locations have settings and special closings

A location represents one restaurant. It owns its locale and address, and is the parent of every settings sub-resource and special closing.

string

Unique identifier, prefixed loc_….

organization_id

string | null

The owning organization (org_…), or null if standalone.

currency

string

One of CHF, EUR, GBP, BRL, USD, MXN.

country

string

One of FR, CH, GB, BR, LU, MX, US.

timezone

string

IANA timezone, e.g. Europe/Zurich.

default_language

string

Default language for the location.

address

object | null

{ line1, line2, postal_code, city, country, latitude, longitude }, or null.

Location

{
  "id": "loc_a1B2c3D4",
  "object": "location",
  "organization_id": "org_8tKx2qP4mN",
  "name": "Trattoria — Geneva",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "Rue du Rhône 42",
    "line2": null,
    "postal_code": "1204",
    "city": "Geneva",
    "country": "CH",
    "latitude": 46.2044,
    "longitude": 6.1432
  },
  "created_at": "2026-01-12T09:31:40Z",
  "updated_at": "2026-05-22T08:15:00Z"
}

Settings sub-resources

Each location exposes five settings objects. Read them with GET and update them with PATCH — except opening_hours, which is replaced wholesale with PUT.

Sub-resource	Object type	Shape (key fields)	Methods
`order_settings`	`order_settings`	`auto_accept_orders`, `average_preparation_time` (`HH:MM`), `enable_multiple_order_per_customer`	`GET`/`PATCH`
`opening_hours`	`opening_hours`	`delivery`, `pickup` — each `{ monday…sunday: [{ from "HH:MM", to "HH:MM" }] }`	`GET`/`PUT`
`delivery_settings`	`delivery_settings`	`delivery_enabled`, `pickup_enabled`, `provider`, `fee_strategy`, `min_order_amount`, `max_order_amount`, `max_items_number`, `max_delivery_radius_in_km`, `fee_percentage`, `max_delivery_fee` (`{amount,currency}` \| `null`), `uber_direct_ums_enabled`	`GET`/`PATCH`
`acceptance_settings`	`acceptance_settings`	`mode` (`online`/`busy`/`paused`), `extra_preparation_time`, `reason`	`GET`/`PATCH`
`ai_instructions`	`ai_instructions`	`chatbot_instructions`	`GET`/`PATCH`

curl https://server.chataigne.ai/v1/locations/loc_a1B2c3D4/acceptance_settings \
  -X PATCH \
  -H "x-api-key: ch_org_live_4f9c2a..." \
  -H "Content-Type: application/json" \
  -d '{ "mode": "busy", "extra_preparation_time": "00:15", "reason": "High demand" }'

opening_hours is a full replacement (PUT), not a merge. Any day you omit is cleared. Always send the complete weekly schedule for both delivery and pickup.

Special closings

A special closing temporarily takes a location offline for a bounded window.

string

Unique identifier, prefixed scl_….

location_id

string

The location this closing applies to (loc_…).

starts_at

string

Start of the closure (ISO 8601 UTC).

ends_at

string

End of the closure (ISO 8601 UTC).

reason

string | null

Optional human-readable reason.

curl https://server.chataigne.ai/v1/locations/loc_a1B2c3D4/special_closings \
  -X POST \
  -H "x-api-key: ch_org_live_4f9c2a..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scl-2026-08-01-summer-break" \
  -d '{
    "starts_at": "2026-08-01T00:00:00Z",
    "ends_at": "2026-08-15T22:00:00Z",
    "reason": "Summer break"
  }'

Response

{
  "id": "scl_9rT5uV6w",
  "object": "special_closing",
  "location_id": "loc_a1B2c3D4",
  "starts_at": "2026-08-01T00:00:00Z",
  "ends_at": "2026-08-15T22:00:00Z",
  "reason": "Summer break",
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T10:00:00Z"
}

How a workspace maps to an API key

The Chataigne API exposes two surfaces, and your key prefix determines which one you can use. Both surfaces authenticate via the x-api-key header.

Chataigne API — /v1

Public surface, scoped to a single organization/location workspace.Key prefix: ch_org_ Base path: /v1

Admin API — /admin/v1

Administrative surface for provisioning organizations and locations.Key prefix: ch_admin_ Base path: /admin/v1

The two surfaces are strictly isolated:

Org key on /v1

200

Works. The key’s workspace defines the organization and locations you can read and write.

Admin key on /v1

403

Rejected with authorization_error.

Org key on /admin/v1

403

Rejected with authorization_error.

Missing key (either surface)

401

Rejected with authentication_error.

Dashboard sessions are not API credentials. A dashboard session cannot be used on /v1 or /admin/v1 — you must use an API key with the correct prefix.

Authenticated request

curl https://server.chataigne.ai/v1/organizations \
  -H "x-api-key: ch_org_live_4f9c2a..."

Listing & pagination

List endpoints return a list object and use cursor-based pagination.

List shape

{
  "object": "list",
  "data": [{ "object": "location", "id": "loc_a1B2c3D4" }],
  "has_more": false,
  "url": "/v1/organizations/org_8tKx2qP4mN/locations"
}

limit

integer

default:"10"

Page size, between 1 and 100.

starting_after

string

Cursor — return items after this id. Mutually exclusive with ending_before.

ending_before

string

Cursor — return items before this id. Mutually exclusive with starting_after.

created_after

string

Filter to items created after this timestamp (ISO 8601).

created_before

string

Filter to items created before this timestamp (ISO 8601).

updated_after

string

Filter to items updated after this timestamp (ISO 8601).

updated_before

string

Filter to items updated before this timestamp (ISO 8601).

Results are ordered by created_at by default.

Expansion

Replace id references with full objects using expand[]. For example, expanding locations on an organization returns each location object inline.

curl "https://server.chataigne.ai/v1/organizations/org_8tKx2qP4mN?expand[]=locations" \
  -H "x-api-key: ch_org_live_4f9c2a..."

Idempotency

Resource-creating POST requests require an Idempotency-Key header.

Replaying the same key with the same body returns the original response, with Idempotent-Replayed: true.
Reusing a key with a different body returns idempotency_error (409).
A concurrent in-flight duplicate returns conflict_error (409).
Keys are retained for 24 hours.

curl https://server.chataigne.ai/v1/organizations/org_8tKx2qP4mN/locations \
  -X POST \
  -H "x-api-key: ch_org_live_4f9c2a..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: loc-geneva-2026-05-29" \
  -d '{ "name": "Trattoria — Lausanne", "currency": "CHF", "country": "CH" }'

Errors

Errors return the relevant HTTP status with a structured body.

{
  "error": {
    "type": "authorization_error",
    "code": "wrong_api_surface",
    "message": "Admin keys cannot access the /v1 surface.",
    "request_id": "req_7Hn2Kp9Qz"
  }
}

Type	Status	When
`invalid_request_error`	`400`	Malformed request or invalid params
`authentication_error`	`401`	Missing or invalid API key
`authorization_error`	`403`	Key not allowed on this surface
`not_found_error`	`404`	Resource does not exist
`conflict_error`	`409`	Concurrent duplicate / state conflict
`idempotency_error`	`409`	Idempotency key reused with new body
`rate_limit_error`	`429`	Per-key rate limit exceeded
`api_error`	`500`	Unexpected server error

The error object may also include param and details. Every response carries an X-Request-Id; error bodies mirror it as error.request_id. You can echo your own id with the x-request-id header.

Rate limits are enforced per key, per surface. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 additionally returns Retry-After.

Versioning

The API is versioned in the path (/v1). Additive changes are non-breaking and ship within the current major version. Breaking changes are introduced under a new major version.

Resource reference

Organizations

GET /v1/organizations, GET/PATCH /v1/organizations/{id}, GET/POST /v1/organizations/{id}/locations

Locations

GET /v1/locations, GET/PATCH /v1/locations/{id}

Settings

order_settings, opening_hours, delivery_settings, acceptance_settings, ai_instructions

Special closings

GET/POST /v1/locations/{id}/special_closings, GET/PATCH/DELETE .../{special_closing_id}

​The domain model

Organizations

Locations

Settings

Special closings

​Organizations contain locations

​Locations have settings and special closings

​Settings sub-resources

​Special closings

​How a workspace maps to an API key

Chataigne API — /v1

Admin API — /admin/v1

​Listing & pagination

​Expansion

​Idempotency

​Errors

​Versioning

​Resource reference

Organizations

Locations

Settings

Special closings

The domain model

Organizations contain locations

Locations have settings and special closings

Settings sub-resources

Special closings

How a workspace maps to an API key

Listing & pagination

Expansion

Idempotency

Errors

Versioning

Resource reference