> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations and locations

> Understand the relationship between business organizations, locations, and API key scope.

Business organizations and locations are the resources you use to identify restaurants in the Chataigne API.

## Business organizations

An `organization` represents a restaurant group or business. It has its own ID and name and can contain multiple locations.

Use a business organization when an integration needs to work across a group—for example, to discover every restaurant, aggregate analytics, or create a new location.

```json theme={null}
{
  "id": "busorg_k3m9x2p7qw",
  "object": "organization",
  "name": "Maison Exemple",
  "image_url": "https://cdn.chataigne.ai/image/org-logo.jpg",
  "location_ids": ["loc_r8v4n2c6tz", "loc_t1q7m5b3dx"]
}
```

### Update an organization profile

Call `PATCH /v1/organizations/{organization_id}` with `businessOrganization.update`. Send `name` and/or `image_url`; omitted fields keep their current value. `image_url` must be a publicly reachable JPG, PNG, or WebP image no larger than 5 MB. Chataigne imports the image and returns its managed URL in the resource. There is no way to clear an existing picture — sending `image_url: null` is rejected with `400 INVALID_IMAGE_URL`, so omit the field to keep the current one.

```bash theme={null}
curl https://server.chataigne.ai/v1/organizations/busorg_k3m9x2p7qw \
  -X PATCH \
  -H "x-api-key: $CHATAIGNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://images.example.com/maison-exemple-logo.png"}'
```

## Locations

A `location` represents one restaurant. Its profile includes information such as its name, currency, country, timezone, language, contact information, and address. Operational settings belong to the location as separate resources.

```json theme={null}
{
  "id": "loc_r8v4n2c6tz",
  "object": "location",
  "organization_id": "busorg_k3m9x2p7qw",
  "name": "Maison Exemple — République",
  "image_url": "https://cdn.chataigne.ai/image/location-logo.jpg",
  "currency": "EUR",
  "country": "FR",
  "timezone": "Europe/Paris",
  "default_language": "fr"
}
```

`organization_id` is `null` for a standalone location.

## How access flows

```text theme={null}
Business-organization-scoped key
└── Business organization
    ├── Location A
    └── Location B

Location-scoped key
└── Location A
```

A business-organization-scoped key can access its organization and child locations, subject to its permissions. Access flows downward to locations, never upward from a location to its parent organization.

A location-scoped key can access only its location. It cannot retrieve a parent organization or sibling location, even when the location belongs to a group.

## Scope does not grant actions

Scope and permissions are evaluated together. For example, a business-organization-scoped key with `location.read` can list child locations but cannot update one without `location.update`. A location-scoped key with `location.update` can update its one location but no other location.

See [API keys and permissions](/concepts/authentication) for the complete permission list.

## Resource IDs

Resource IDs are opaque strings. You should:

* Read IDs from API responses.
* Store them with your integration's records.
* Pass them unchanged in endpoint paths.
* Avoid parsing them or assuming their length or internal structure.

Use [Find your resources](/getting-started/find-your-resources) to discover the IDs available to your key.