{
  "openapi": "3.1.0",
  "info": {
    "title": "Sous Chef Onboarding API",
    "summary": "Open new locations from your own systems: create a location, then add your brands to it, each with its menu and its stores, ready to go live when you choose.",
    "version": "0.1.0-draft",
    "description": "The Sous Chef Onboarding API lets multi-location operators open new locations on Sous Chef from\ntheir own systems. Create a location and add the brands that will sell from it. Each brand gets\nits own copy of its menu and its stores there, with no ticket, form or onboarding call. Going live\non a delivery platform is a separate, deliberate step.\n\n## Shape of every call\n\nEvery operation is a **POST** with a single JSON body and a single JSON reply. There are no path\nparameters and no query strings, so a request is fully described by its URL and its body.\n\nThe base path carries **no version segment**. Changes are additive: new fields and new operations\nare added, and nothing published is removed or narrowed. Write your client to ignore fields it\ndoes not recognise and it keeps working across releases.\n\n## Authentication\n\nSend **both** headers on every request:\n\n- `x-api-key`: your partner API key, issued per organization.\n- `x-mealco-org-id`: the organization the call acts on behalf of. It must be the organization\n  the key belongs to; a mismatch is rejected with `401`.\n\nBoth are required together. Neither is sufficient alone.\n\n## Conventions worth learning once\n\n- **Opening hours are local times.** They are 24-hour `HH:mm` in the location's own IANA\n  timezone, which you send on `createLocation`. This API has no timestamp fields.\n- **Join on IDs, never on display names.** The `brandId` `fetchProvisionableBrands` returns is what\n  you pass back to `addBrandsToLocation`. Names are for showing a person, not for matching a\n  record.\n- **Writes here are safe to retry.** `createLocation` and `addBrandsToLocation` are both\n  idempotent. See **Concepts → Retries and idempotency**. Neither needs an idempotency key: you\n  retry by sending the same input again.\n- **Provisioned locations are ready to build on.** Each brand you add gets a copy of its master\n  menu and its stores. Going live on a delivery platform is a separate, deliberate step. Your\n  organization and brands are set up with us once, before your first call. See **Concepts → What\n  \"provisioned\" means**.\n\nEvery route under `paths` states whether it is safe to retry, derived from the endpoint's\ndeclared side-effect contract. It covers routes only: a webhook is a call we send, and we\nretry its delivery ourselves, so a webhook carries no retry sentence.\n\n| declared operation | read-only | destructive | idempotent |\n|---|---|---|---|\n| read | yes | no | yes |\n| write-idempotent | no | yes | yes |\n| write | no | yes | no |"
  },
  "servers": [
    {
      "url": "https://api.yoursouschef.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Onboarding",
      "description": "The Sous Chef Onboarding API: provisioning for operators whose own systems open new locations.\n\nAll endpoints are POST with a single JSON body. The base path carries no version segment.\nChanges to this API are additive: new fields and new endpoints.\n\nAuthentication: every request must carry both `x-api-key` and `x-mealco-org-id`, and they must\nagree. The key alone determines the organization; the header must state the same one or the\nrequest is rejected. A partner therefore cannot act on an organization it did not name.\n\nScope: a provisioned location is ready to build on. A new store takes no orders yet, is not yet\nconnected to its delivery platform, and its menu is not yet visible to guests. Putting a store\nlive on a delivery platform is a separate step.\nYour organization and brands are set up with us before your first call."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "OrganizationId": []
    }
  ],
  "paths": {
    "/onboarding/fetchProvisionableBrands": {
      "post": {
        "operationId": "fetchProvisionableBrands",
        "summary": "List provisionable brands",
        "description": "List the brands this organization owns. These are the candidates for provisioning at a\nlocation, and the source of the `brandId`s `addBrandsToLocation` needs.\n\nThe list is not filtered to brands that can be provisioned: a brand can be listed here and\nstill come back `MASTER_MENU_NOT_FOUND` or `MASTER_MENU_AMBIGUOUS` from\n`addBrandsToLocation` for that brand. That write is the authoritative check; this read\nis not. Brands are excluded only once retired, never for being unready to provision.\n\nSafe to retry: this operation is read-only and idempotent.",
        "tags": [
          "Onboarding"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "FetchProvisionableBrandsRequest",
                "description": "Request for `fetchProvisionableBrands`. It takes no arguments: the organization comes from\nthe api key, not the body.",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The active brands your organization owns, up to 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "FetchProvisionableBrandsResponse",
                  "description": "Reply from `fetchProvisionableBrands`.",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProvisionableBrand"
                      },
                      "description": "The active brands the organization owns, up to 200. Not filtered to brands that can be\nprovisioned. See the `fetchProvisionableBrands` operation."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/onboarding/createLocation": {
      "post": {
        "operationId": "createLocation",
        "summary": "Create a location",
        "description": "Create a location.\n\nSafe to retry. The location code is made of a short prefix that we set up for your\norganization before your first call, your `storeNumber` and `state`, so a repeated call with\nthe same `storeNumber` and `state` returns the existing location with `created: false`. A\nretry never creates a second location and never modifies the first. This operation does not\ncorrect a field on an existing location.\n\nSafe to retry: this operation changes state but is idempotent.",
        "tags": [
          "Onboarding"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "CreateLocationRequest",
                "description": "Request for `createLocation`.",
                "properties": {
                  "storeNumber": {
                    "type": "number",
                    "description": "Your own number for this location, a whole number from 1 to 99999. Required. It is not a\nlabel: it forms part of our location code, which is a short prefix that we set up for your\norganization before your first call, then your `storeNumber`, then `state`, e.g. `AB347DE`\nfor an organization whose prefix is `AB`. Sending the same number again (with the same\n`state`) returns the existing location, which makes a retry safe. Sending a different number\ncreates a different location."
                  },
                  "state": {
                    "type": "string",
                    "description": "Two-letter US state code, e.g. `NC`. Required. It forms part of the location code.\nCase-insensitive in the request; always uppercase in the code."
                  },
                  "displayName": {
                    "type": "string",
                    "description": "Restaurant name as it should read for staff, e.g. \"Example Kitchen\". Required."
                  },
                  "address": {
                    "type": "string",
                    "description": "Street address, one line."
                  },
                  "unitNumber": {
                    "type": "string",
                    "description": "Unit or suite within the building, e.g. \"Suite 200\"."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone, e.g. `America/New_York`. Required. Your opening hours are interpreted in this\ntimezone. It is not derived from `state`. A missing value, or an abbreviation such as `PST`,\nis rejected with `400`."
                  },
                  "phone": {
                    "type": "string",
                    "description": "Contact phone in E.164, e.g. `+12035550147`."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Free-text notes stored with the location. Not shown to guests."
                  },
                  "hours": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/BusinessHoursWindow"
                    },
                    "description": "Opening hours. Omit to leave hours unset and configure them later in the portal. Each\nwindow needs its `day`, `startTime` and `endTime`: a window that lacks one is not stored."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The location, and whether this call created it or found it from an earlier call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "CreateLocationResponse",
                  "description": "Reply from `createLocation`.",
                  "properties": {
                    "location": {
                      "$ref": "#/components/schemas/LocationSummary",
                      "description": "The location: newly created when `created` is `true`, or the existing one for this\n`storeNumber`/`state` pair when `created` is `false` and this was a retry."
                    },
                    "created": {
                      "type": "boolean",
                      "description": "`true` when this call created the location, `false` when it already existed and this was a\nretry. Either way the location in `location` is yours and ready for `addBrandsToLocation`."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/onboarding/addBrandsToLocation": {
      "post": {
        "operationId": "addBrandsToLocation",
        "summary": "Add brands to a location",
        "description": "Provision brands at an existing location: brand location, a copy of each brand's master menu,\nand one store, not yet live, for each of DoorDash, Uber Eats and Grubhub.\n\nSafe to retry, and safe to call again later to add more brands. A brand already provisioned\nat the location is reported as `status: \"alreadyProvisioned\"` and nothing is written for it.\nEach brand succeeds or fails independently: one brand failing leaves the others, and the\nlocation, in place.\n\nSafe to retry: this operation changes state but is idempotent.",
        "tags": [
          "Onboarding"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "title": "AddBrandsToLocationRequest",
                "description": "Request for `addBrandsToLocation`.",
                "properties": {
                  "locationId": {
                    "type": "string",
                    "description": "The `locationId` returned by `createLocation`. Required."
                  },
                  "brandIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Brand ids from `fetchProvisionableBrands`. Required, 1 to 20 per call. Ids already\nprovisioned at this location are reported and skipped, not rejected."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One outcome per requested brand, in request order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "AddBrandsToLocationResponse",
                  "description": "Reply from `addBrandsToLocation`.",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProvisionedBrand"
                      },
                      "description": "One entry per brand id in the request, in the same order."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BusinessHoursWindow": {
        "type": "object",
        "description": "One opening window on one day.",
        "properties": {
          "day": {
            "$ref": "#/components/schemas/BusinessHoursWindowDay",
            "description": "Day of week this window applies to.\n\nThe day is a name, not an index, because day-of-week numbering differs between systems."
          },
          "startTime": {
            "type": "string",
            "description": "Local opening time, 24-hour `HH:mm`, e.g. `09:00`. Interpreted in the location's timezone."
          },
          "endTime": {
            "type": "string",
            "description": "Local closing time, 24-hour `HH:mm`. A window ending past midnight belongs to the day it\nstarts on, e.g. Friday 22:00-02:00 is one Friday window, not a Friday and a Saturday one."
          }
        }
      },
      "BusinessHoursWindowDay": {
        "type": "string",
        "description": "Day of week a `BusinessHoursWindow` applies to.",
        "enum": [
          "monday",
          "tuesday",
          "wednesday",
          "thursday",
          "friday",
          "saturday",
          "sunday"
        ]
      },
      "LocationSummary": {
        "type": "object",
        "description": "The location, as we hold it.",
        "properties": {
          "locationId": {
            "type": "string",
            "description": "Our identifier for the location. Send this to `addBrandsToLocation`."
          },
          "code": {
            "type": "string",
            "description": "Our location code, e.g. `AB347DE`: the short prefix set up for your organization (`AB` in\nthis example), then your `storeNumber` and `state`. It appears, in lowercase, in the\n`externalId` of every store at the location, so it is worth storing on your side."
          },
          "displayName": {
            "type": "string",
            "description": "The name we recorded."
          },
          "timezone": {
            "type": "string",
            "description": "The IANA timezone in effect."
          }
        }
      },
      "ProvisionableBrand": {
        "type": "object",
        "description": "A brand this organization owns and may be able to provision at a location. See\n`fetchProvisionableBrands` for what \"may\" means.",
        "properties": {
          "brandId": {
            "type": "string",
            "description": "Our identifier for the brand. Send this to `addBrandsToLocation`; never send the name."
          },
          "slug": {
            "type": "string",
            "description": "The brand's short name, e.g. `greatburgerco`. It appears in the `externalId` of every store\nof the brand, so it also lets you predict `externalId` before the store exists."
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name, e.g. \"Great Burger Co\". For display only. Never send it\nback to us as an identifier."
          }
        }
      },
      "ProvisionedBrand": {
        "type": "object",
        "description": "The outcome for one requested brand.",
        "properties": {
          "brandId": {
            "type": "string",
            "description": "The brand id you sent."
          },
          "status": {
            "$ref": "#/components/schemas/ProvisionedBrandStatus",
            "description": "`provisioned`: created by this call. `alreadyProvisioned`: present before this call,\nnothing written. `failed`: see `errorCode` and `errorMessage`; other brands in the same\nrequest are unaffected."
          },
          "menuId": {
            "type": "string",
            "description": "The copy of the brand's master menu made for this location. Absent when `status` is\n`failed`, and it can be absent when `status` is `alreadyProvisioned`."
          },
          "stores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProvisionedStore"
            },
            "description": "Up to one store per delivery platform: DoorDash, Uber Eats and Grubhub. All are created\ninert: not active, not integrated, not published. Nothing here is visible to a guest until\nit is published."
          },
          "errorCode": {
            "type": "string",
            "description": "Machine-readable failure reason, e.g. `MASTER_MENU_NOT_FOUND`, `UNKNOWN_BRAND`."
          },
          "errorMessage": {
            "type": "string",
            "description": "Human-readable failure reason, safe to log and to show your own operators."
          }
        }
      },
      "ProvisionedBrandStatus": {
        "type": "string",
        "description": "The outcome for one requested brand. See `ProvisionedBrand.status`.",
        "enum": [
          "provisioned",
          "alreadyProvisioned",
          "failed"
        ]
      },
      "ProvisionedStore": {
        "type": "object",
        "description": "One store created for one brand on one delivery platform.",
        "properties": {
          "platform": {
            "type": "string",
            "description": "Delivery platform, for example `doordash`, `ubereats`, `grubhub`. This is not a closed\nlist: delivery platforms can be added, so treat it as an open set and do not validate it\nagainst the examples given here."
          },
          "storeId": {
            "type": "string",
            "description": "Our identifier for the store."
          },
          "externalId": {
            "type": "string",
            "description": "The identifier the delivery platform will know this store by (its\n`merchant_supplied_id`), e.g. `dd-ab347de-greatburgerco`. Store it: it is used to trace\norder routing when you report a problem."
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Sous Chef partner API key. Issued per organization; treat it as a secret and send it on every request."
      },
      "OrganizationId": {
        "type": "apiKey",
        "in": "header",
        "name": "x-mealco-org-id",
        "description": "The organization the request acts on behalf of. Required, and must be the organization the API key belongs to. A mismatch is rejected with 401."
      }
    }
  }
}
