API docs
Sous Chef Management API
Request access

Authentication

Send both headers on every request:

HeaderMeaning
x-api-keyYour partner API key, issued per organization. Treat it as a secret.
x-mealco-org-idThe organization the call acts on behalf of.

They are required together, and the organization id must be the organization the key belongs to. A mismatch is rejected with 401. It is not reinterpreted as the key's own organization.

Scope

A credential is scoped to exactly one organization. There is no request parameter that widens that scope, which is why organizationId never appears in a request body: an operation cannot be pointed at data the credential does not already reach.

Handling keys

  • Keep the key server-side. It is a bearer credential: anyone who holds it can act as you.
  • Rotate by requesting a new key, moving traffic to it, then retiring the old one. Both are live during the overlap, so a rotation needs no downtime window.
  • If a key is exposed, contact support@yoursouschef.com immediately. A compromised key is revoked, not rotated on a schedule.

Rate limits

Rate limits apply per organization and per kind of operation. Directory and status reads have the highest limit. Paged reads such as fetchOrders have a lower one. Writes that reach the delivery platforms, menu publishing and report requests have the lowest. Every limit is counted over a 60-second window.

  • A limit is per organization, not per key. All of your keys draw on the same budgets, so adding keys does not multiply your throughput and rotating a key does not reset your usage. Send x-mealco-org-id on every request. It is required for authentication.
  • 429 is part of the contract. Any operation may answer it. Honour Retry-After when it is present; when it is not, wait 60 seconds and add jitter. Either way, do not tight-loop. See Getting Started → Errors and retries.

Two properties of the API keep a polling integration inside its limits:

  • Store, status, menu and order reads are answered from Sous Chef's own refreshed state, never proxied per request to the platforms. Your cadence is bounded by your limits alone, never by a platform's. The Uber Eats promotion reads are the exception: they call Uber Eats on each request. See Concepts → Data freshness.
  • Reads are bulk-shaped. fetchStoreStatuses takes many storefronts in one call, and fetchStores pages through the whole crosswalk at up to 100 rows a page. A status sweep across a large estate is a handful of calls, not one per store.

If your expected volume needs more than the standard limits (for example, a frequent status sweep across every store), send the cadence you need to support@yoursouschef.com.

What a failure looks like

  • 401: the key is missing, unknown, revoked, or does not match the organization id.
  • 403: the key is valid but does not have the permission that the operation needs, for example a read-only key on a write.
  • 429: you are over your rate limit. See Rate limits above and Errors and retries.