This is the full developer documentation for CreatoRain API # CreatoRain API > Real creator videos for your restaurants, by API. Not live yet The API is not open on production yet. These docs describe what is built, and mark plainly what is not. ## What the API does CreatoRain sends local food creators to your restaurants. Each creator visits, posts a real video and gets measured. The API lets your own server or AI agent add stores to the CreatoRain Network. It reads back visits, posted videos and their public numbers. It previews what the month will cost. Its video-production reads never charge you. ## Two products * **Video production.** Add stores, and creators visit and post. This is the API’s main feature. Start with [Video production](https://docs.creatorain.com/guides/video-production/). * **Creator data.** Search and enrich public creator profiles. **(Not live yet)** See [Creator data](https://docs.creatorain.com/guides/creator-data/). One USD balance pays for both. See [Pricing and wallet](https://docs.creatorain.com/pricing/). ## Start here * [Quick start](https://docs.creatorain.com/get-started/quick-start/): your first calls, on the sandbox. * [Agent quick start](https://docs.creatorain.com/get-started/agent-quick-start/): how an AI agent gets a key from its human. * [Errors](https://docs.creatorain.com/errors/): every error code, one anchor each. * [API console](https://docs.creatorain.com/reference/console/): browse the spec. * For agents: [llms.txt](https://docs.creatorain.com/llms.txt). Every page also has a markdown copy: add `.md` to its path. # Agent quick start > How an AI agent with no key gets one from its human, with an onboarding session (RFC 8628 style). An AI agent should never ask its human to paste a key into a chat. It opens an **onboarding session** instead. The human approves it in the CreatoRain app, and the agent collects the key once. The flow follows the OAuth device grant (RFC 8628). Not live yet The session calls are built. The approval page in the app (`/settings/api/connect`) is not live yet, and the API is not open on production. ## 1. Open a session (no key) ```sh curl -X POST "$CREATORAIN_API/onboarding_sessions" \ -H "Content-Type: application/json" \ -d '{"client_name":"My agent","requested_scopes":["read","locations:write"],"requested_livemode":false}' ``` The `201` answer carries: * `user_code`: eight letters, such as `BCDF-GHJK`. Show it to your human. * `url`: the app page where your human types the code. * `session_secret` (`crp_obs_...`): shown **once**. It is the only way to poll. Store it like a key. * `interval`: seconds between polls. * `expires_at`: 15 minutes after creation. The scopes and mode you ask for are a request only. The human decides. ## 2. Show your human the code and the link Say what you need and why. The workspace owner signs in, enters the code and approves. They pick the mode and the scopes. ## 3. Poll ```sh curl "$CREATORAIN_API/onboarding_sessions/obs_..." \ -H "Authorization: Bearer $SESSION_SECRET" ``` * Poll every `interval` seconds. Sooner is `429 slow_down`. The interval then grows by 5 seconds, up to 60, and `Retry-After` carries it. * `status` is `pending`, `approved`, `denied` or `expired`. * The **first** poll after approval carries `key.secret`. No later poll does: `key_delivered` turns `true`. * Lost the key? `next_action` is `create_new_session`. Open a new session. * `blockers` say why an approval cannot make a key yet. For example `live_key_requires_top_up`, `key_limit_reached` or `owner_changed`. A wrong secret and an unknown id both answer `404`. Failures count toward the address block, like bad keys. ## Limits 5 sessions an hour per address, plus a global per-minute ceiling. Over it: `429 rate_limited` with `Retry-After`. ## Next Use the key as in the [Quick start](https://docs.creatorain.com/get-started/quick-start/). Read [llms.txt](https://docs.creatorain.com/llms.txt) for the agent instructions. # Authentication and keys > API keys, live and test modes, scopes, IP allowlists and the failed-auth block. Every call sends a key in the `Authorization` header: ```http Authorization: Bearer crp_test_... ``` Never put a key in a URL, a log or client-side code. ## Hosts | Mode | Host | Keys | | ------- | --------------------------------------- | --------------------------------- | | Live | `https://api.creatorain.com/v1` | `crp_live_...`, `crp_rk_live_...` | | Sandbox | `https://sandbox.api.creatorain.com/v1` | `crp_test_...`, `crp_rk_test_...` | Not live yet Neither host answers yet. Until `api.creatorain.com` resolves, the live API will also answer at `https://data.creatorain.com/v1`. ## Key kinds * `crp_live_` and `crp_test_`: standard keys, live and sandbox. * `crp_rk_live_` and `crp_rk_test_`: restricted keys, same modes. * `crp_obs_`: an onboarding session secret. It polls one session and nothing else. See [Agent quick start](https://docs.creatorain.com/get-started/agent-quick-start/). A test key on the live host is `401 test_key_on_live`. A live key on the sandbox is `401 live_key_on_sandbox`. A key is shown once, when it is made. CreatoRain stores only a hash of it. A key acts for **one workspace**. ## Scopes | Scope | Lets the key | | ----------------- | ------------------------------------------------------------- | | `read` | Read the account, locations, visits, videos and bill preview. | | `samples:read` | Read creator samples. **(Not live yet)** | | `locations:write` | Add stores. | | `balance:write` | Top up, refund, lower limits. **(Not live yet)** | | `creators:read` | Creator data. **(Not live yet)** | | `webhooks:write` | Manage webhook endpoints. **(Not live yet)** | A call without the scope it needs is `403 scope_missing`. ## IP allowlist A key may carry an IP allowlist. A request from another address is `403 forbidden_ip`. ## Failed authentication Twenty failed authentications (missing or unknown key) from one address within a minute block that address for 15 minutes. ## Live keys A live key needs one paid top-up on the account first. See [Going live](https://docs.creatorain.com/get-started/going-live/). ## Leaked keys Live key prefixes will be registered with GitHub secret scanning, so a leaked key is revoked on report. **(Not live yet)** # Going live > From test keys to live keys, and the first top-up. Not live yet The API is not open on production yet. Live keys and top-ups are not live. ## Checklist 1. Your code runs end to end on the [sandbox](https://docs.creatorain.com/get-started/sandbox/). 2. You send an `Idempotency-Key` on every POST. See [Conventions](https://docs.creatorain.com/guides/conventions/). 3. You branch on `error.code` and handle `429` with `Retry-After`. See [Errors](https://docs.creatorain.com/errors/). 4. Make a **first top-up** in the app. A live key needs one paid top-up. Without it, key approval answers `live_key_requires_top_up`. 5. Create a live key (`crp_live_...`) with only the scopes you need. 6. Switch your base URL to the live host and your key to the live key. ## What costs money * A posted creator video, at the store’s locked price per video. * Billed creator-data calls. **(Not live yet)** Video-production reads, dry runs and the bill preview never charge. Creator-data reads are billed. See [Pricing and wallet](https://docs.creatorain.com/pricing/). ## Set limits first Set daily and monthly spend limits before you scale. See [Spend limits](https://docs.creatorain.com/pricing/spend-limits/). **(Not live yet)** # Quick start > Your first CreatoRain API calls on the sandbox, in about 15 minutes. Not live yet The sandbox host is not up yet, and the API is not open on production. The steps below are the calls as built. They will run once the sandbox opens. You need a test key (`crp_test_...`) and a terminal. Set two variables once: ```sh export CREATORAIN_API="https://sandbox.api.creatorain.com/v1" export CREATORAIN_KEY="crp_test_..." ``` ## 1. Get a test key A workspace owner creates keys in the app, under **Settings > API**. **(Not live yet)** An AI agent with no key can ask its human for one. See [Agent quick start](https://docs.creatorain.com/get-started/agent-quick-start/). ## 2. Read your account ```sh curl "$CREATORAIN_API/account" -H "Authorization: Bearer $CREATORAIN_KEY" ``` The answer has your account `status`, `counting_locations` and `blockers`. See [States and blockers](https://docs.creatorain.com/guides/states-and-blockers/). ## 3. Quote a store first, with a dry run A dry run checks the request and quotes it. It writes no store. ```sh curl -X POST "$CREATORAIN_API/locations?dry_run=true" \ -H "Authorization: Bearer $CREATORAIN_KEY" \ -H "Idempotency-Key: quickstart-dry-1" \ -H "Content-Type: application/json" \ -d '{"name":"Sexy Crab Duluth","address":"2416 Pleasant Hill Rd, Duluth, GA 30096","videos_per_month":4,"accepted_terms":"network-2026-10"}' ``` The answer shows `price_per_video_cents` and the `deposit` quote. `deposit.charged` is always `false`. ## 4. Add the store Send the same body without `dry_run`, with a new `Idempotency-Key`. The store is created **on hold** (`state: on_hold`). Nothing books it until CreatoRain releases it. ## 5. Watch it work ```sh curl "$CREATORAIN_API/locations" -H "Authorization: Bearer $CREATORAIN_KEY" curl "$CREATORAIN_API/visits" -H "Authorization: Bearer $CREATORAIN_KEY" curl "$CREATORAIN_API/videos" -H "Authorization: Bearer $CREATORAIN_KEY" curl "$CREATORAIN_API/bill/preview" -H "Authorization: Bearer $CREATORAIN_KEY" ``` On the sandbox, a simulator moves a store through its life in minutes. **(Not live yet)** ## Next * [Authentication and keys](https://docs.creatorain.com/get-started/authentication/) * [Conventions](https://docs.creatorain.com/guides/conventions/): ids, times, money, paging, idempotency. * [Going live](https://docs.creatorain.com/get-started/going-live/) # Sandbox > Test keys, fixture data and a fast clock, so a store's whole life runs in minutes with no real spend. Not live yet The sandbox is not up yet. This page describes it as designed. The sandbox runs the same API with **test keys** (`crp_test_...`) at `https://sandbox.api.creatorain.com/v1`. Nothing there costs money, and no real creator is contacted. ## What is different * **Fixtures only.** Test keys read fixture creators, never real ones. Fixture emails end in `sandbox.invalid`. * **Your own sandbox.** Each workspace gets its own sandbox campaign. No other client’s data mixes in. * **A fast clock.** A simulator moves each store through matched, booked, visited, posted and billed in minutes. * **Same shapes.** The rows, ledger entries and webhooks look like live ones, with `livemode: false`. ## Sandbox-only calls Test keys only. A live key gets `404`. * `POST /v1/sandbox/top_ups`: add test money. * `POST /v1/sandbox/locations/{id}/advance`: move a store to a later state. * `POST /v1/sandbox/scenarios`: force a case, such as `no_show`, `video_taken_down`, `balance_low` or `top_up_failed`. * `POST /v1/sandbox/clock`: change the clock mode. * `POST /v1/sandbox/reset`: start over. ## The console The [API console](https://docs.creatorain.com/reference/console/) will send requests to the sandbox only, with test keys. Try-it never reaches a live host. # Conventions > Ids, times, money, pagination, idempotency, dry runs, request ids and versioning. ## Ids Ids are opaque strings with a prefix: `acct_`, `loc_`, `vis_`, `vid_`, `key_`, `obs_`. Do not parse them. ## Times * RFC 3339. * A location’s `created_at` is in UTC. * A visit’s times, and a video’s `published_at`, are on the **store’s** offset: the restaurant’s wall clock. `timezone` carries its IANA zone. * Months are `YYYY-MM`, counted on each store’s own clock. ## Money Integer cents, with `currency: "USD"`. API usage is priced in micro-dollars (1 USD = 1,000,000). **(Not live yet)** ## Pagination Lists take `limit` (1 to 200, default 50) and `cursor`. * Pass the previous page’s `next_cursor` unchanged. Leave it out for the first page. * `next_cursor` is `null` on the last page. * A changed cursor is `400 parameter_invalid` (field `cursor`). * Visits page by last update, so a visit can appear again on a later page. Dedupe on `id`. ## Idempotency Send `Idempotency-Key` on every POST, PATCH and DELETE. It is **required** on money calls and location creates. * Up to 255 printable ASCII characters, no spaces. * A retry with the same key and body gets the stored answer, with `Idempotent-Replayed: true`, for 24 hours. * The same key with a different body is `409 idempotency_conflict`. * A duplicate while the first is still running is `409 idempotency_in_progress`. * A `400` or `5xx` answer is not stored, so a corrected retry may reuse the key. ## Dry runs `dry_run=true` on a create checks and quotes, with the same refusals as a live call. It writes no store. Ids come back `null`. The `Idempotency-Key` is still stored. ## Request ids Every answer has a `Request-Id` header. It equals `error.request_id`. Quote it to support. ## Errors Every error has one envelope: ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "...", "field": "limit", "doc_url": "https://docs.creatorain.com/errors#parameter_invalid", "request_id": "..." } } ``` Branch on `code`. See [Errors](https://docs.creatorain.com/errors/). ## Versioning * The major version is in the path: `/v1`. * Changes inside v1 are additive: new fields, new endpoints, new codes. Ignore fields you do not know. * A breaking change ships as `/v2`, with 6 months of overlap. * A `CreatoRain-Version` header is reserved. **(Not live yet)** See the [Changelog](https://docs.creatorain.com/changelog/). # Errors > Every CreatoRain API v1 error code, its HTTP status and type, and how to fix it. One anchor per code. Every error has one envelope: ```json { "error": { "type": "permission_error", "code": "scope_missing", "message": "...", "field": "...", "doc_url": "https://docs.creatorain.com/errors#scope_missing", "request_id": "..." } } ``` * **Branch on `code`**, never on `message`. Messages may change. * `type` groups codes: `invalid_request_error`, `authentication_error`, `permission_error`, `idempotency_error`, `rate_limit_error`, `api_error`. * `field` names the request field at fault, when one is. * `request_id` equals the `Request-Id` header. Quote it to support. * A `5xx` message never carries a cause. Each code below has its own anchor, `/errors#`. A code marked **Not live yet** is designed, but no live route returns it yet. Note Today an error’s `doc_url` still points at the old www address. It moves to this page at launch. ## 400 Bad request ### `parameter_invalid` HTTP 400, type `invalid_request_error`. A query or body field is wrong. `field` names it. A cursor you changed is this error too. **Fix:** Correct the field named in `field` and retry. ### `invalid_json` HTTP 400, type `invalid_request_error`. The request body is not valid JSON. **Fix:** Send a valid JSON body with `Content-Type: application/json`. ### `idempotency_key_invalid` HTTP 400, type `invalid_request_error`. The `Idempotency-Key` header is empty, longer than 255 characters, or has spaces or non-printable characters. **Fix:** Send 1 to 255 printable ASCII characters, no spaces. ### `idempotency_key_required` HTTP 400, type `invalid_request_error`. This call needs an `Idempotency-Key` header. Location creates and money calls require one. A dry run needs one too. **Fix:** Add a unique `Idempotency-Key` per logical request. ### `customization_not_supported` HTTP 400, type `invalid_request_error`. The request set a creator field, such as `min_followers`, `rules` or `approval_mode`. CreatoRain chooses the creators. **Fix:** Remove every creator field from the request. ### `videos_per_month_out_of_range` HTTP 400, type `invalid_request_error`. `videos_per_month` is outside the plan's range. Paid: 2 to 10. Free: exactly the free plan's videos. **Fix:** Send a value inside the range. ### `batch_invalid` HTTP 400, type `invalid_request_error`. A batch had one or more refused items. Nothing was written. `error.items` lists each refused item by index. **Fix:** Fix every item in `error.items` and send the whole batch again. ### `terms_not_accepted` HTTP 400, type `invalid_request_error`. A new or returning store needs `accepted_terms`, the network terms version accepted. **Fix:** Send `accepted_terms` with the terms version the store accepted. ### `invalid_filter` HTTP 400, type `invalid_request_error`. Not returned: see [`parameter_invalid`](#parameter_invalid). Named in the design for a bad search filter. The API does not return it: a bad filter answers `parameter_invalid`. **Fix:** Handle `parameter_invalid`. ### `invalid_request` HTTP 400, type `invalid_request_error`. Not returned: see [`parameter_invalid`](#parameter_invalid). Named in the design for a bad request field. The API does not return it: a bad field answers `parameter_invalid`. **Fix:** Handle `parameter_invalid`. ### `cursor_expired` HTTP 400, type `invalid_request_error`. Not returned: see [`parameter_invalid`](#parameter_invalid). Named in the design for a cursor that no longer works. The API does not return it: a changed cursor answers `parameter_invalid`. **Fix:** Handle `parameter_invalid`, then start the list again without a cursor. ## 401 Unauthorized ### `invalid_key` HTTP 401, type `authentication_error`. The key is missing, unknown or revoked. **Fix:** Send `Authorization: Bearer ` with an active key. ### `test_key_on_live` HTTP 401, type `authentication_error`. A `crp_test_` key was sent to the live host. **Fix:** Use a live key on live, or call the sandbox. ### `live_key_on_sandbox` HTTP 401, type `authentication_error`. A `crp_live_` key was sent to the sandbox. **Fix:** Use a test key on the sandbox. ## 402 Payment required ### `insufficient_balance` **(Not live yet)** HTTP 402, type `invalid_request_error`. Your balance cannot cover this call. A batch create with `require_funded: true` and a billed creator-data call answer it. A store added without `require_funded` waits in `awaiting_payment` instead. **Fix:** Top up, then retry with a new `Idempotency-Key`. A 402 answer is stored for the old key. ### `spend_limit_reached` **(Not live yet)** HTTP 402, type `invalid_request_error`. Not in the v1 spec yet. A creator-data call would go over the daily or monthly data spend limit. Nothing is billed. **Fix:** Wait for the next day or month, or raise the limit in the app. Retry with a new `Idempotency-Key`. ### `max_cost_exceeded` **(Not live yet)** HTTP 402, type `invalid_request_error`. Not in the v1 spec yet. The call's worst-case cost is above the `max_cost_cents` you sent. It did not run. **Fix:** Raise `max_cost_cents`, or ask for fewer rows. Retry with a new `Idempotency-Key`. ### `reveal_expired` **(Not live yet)** HTTP 402, type `invalid_request_error`. Not in the v1 spec yet. `GET /v1/creators/{id}` came more than 30 days after the last paid read of that creator. A GET never spends money. **Fix:** Call `POST /v1/creators/enrich/handle` to read the creator again (billed). ## 403 Forbidden ### `scope_missing` HTTP 403, type `permission_error`. The key lacks the scope this route needs. **Fix:** Create a key with the scope, or ask the workspace owner. ### `forbidden_ip` HTTP 403, type `permission_error`. The key has an IP allowlist, and this request came from another address. **Fix:** Call from an allowed address, or update the allowlist in the app. ### `forbidden` HTTP 403, type `permission_error`. The action is not allowed for this account. **Fix:** Check the account's state with `GET /account`. ### `live_key_requires_top_up` HTTP 403, type `permission_error`. A live key needs one paid top-up on the account first. **Fix:** Make a first top-up in the app, then approve the key again. ### `limit_raise_requires_dashboard` **(Not live yet)** HTTP 403, type `permission_error`. The API can lower a spend limit, never raise one. **Fix:** Raise the limit in the app. ## 404 Not found ### `not_found` HTTP 404, type `invalid_request_error`. No such object for this account. A malformed id, an unknown id and another account's id all answer the same. **Fix:** Check the id and the key's workspace. ## 409 Conflict ### `idempotency_conflict` HTTP 409, type `idempotency_error`. The same `Idempotency-Key` was sent with a different body. **Fix:** Use a new key for a new request. ### `idempotency_in_progress` HTTP 409, type `idempotency_error`. The first request with this key is still running. **Fix:** Wait, then retry with the same key and body. ### `conflict` HTTP 409, type `invalid_request_error`. The request conflicts with the object's current state. **Fix:** Read the object again, then retry. ### `location_already_in_network` HTTP 409, type `invalid_request_error`. Another team of this account holds the place, or the same place is listed under another name. **Fix:** Use the existing location, or ask the team that holds it. ### `external_id_conflict` **(Not live yet)** HTTP 409, type `invalid_request_error`. Your `external_id` label is already used in this workspace. **Fix:** Use a unique `external_id`. ### `dispute_open` **(Not live yet)** HTTP 409, type `invalid_request_error`. A card dispute is open on this account. **Fix:** Contact support with the `request_id`. ### `job_limit_reached` **(Not live yet)** HTTP 409, type `invalid_request_error`. Not in the v1 spec yet. The account already has 5 active creator-data jobs. **Fix:** Wait for a job to finish, then create the new one. ## 413 Request too large ### `request_too_large` HTTP 413, type `invalid_request_error`. The request body is too large. **Fix:** Send fewer items per request. A batch takes at most 50 locations. ## 422 Unprocessable ### `address_not_verified` **(Not live yet)** HTTP 422, type `invalid_request_error`. The store's address could not be verified. **Fix:** Send the full street address, or a `google_place_id`. ### `not_food_business` **(Not live yet)** HTTP 422, type `invalid_request_error`. The place is not a restaurant or food business. **Fix:** Check the address or place id. ### `metro_not_served` **(Not live yet)** HTTP 422, type `invalid_request_error`. CreatoRain does not serve this metro yet. **Fix:** Try again later, or contact support. ### `package_not_available` HTTP 422, type `invalid_request_error`. The plan asked for is not the account's plan, or a free-plan account tried to bring back a store that already ran its free term. **Fix:** Omit `plan` to use the account's plan. ### `account_location_limit` **(Not live yet)** HTTP 422, type `invalid_request_error`. The account has reached its location limit. **Fix:** Contact support to raise it. ### `commit_limit_exceeded` **(Not live yet)** HTTP 422, type `invalid_request_error`. The call would go over the account's monthly spend limit. **Fix:** Raise the limit in the app, or plan fewer videos. ### `top_up_exceeds_feasible` **(Not live yet)** HTTP 422, type `invalid_request_error`. The top-up is larger than the account can spend soon. **Fix:** Top up a smaller amount. ### `no_saved_card` **(Not live yet)** HTTP 422, type `invalid_request_error`. The call needs a saved card, and the account has none. **Fix:** Save a card in the app. ### `data_price_not_set` **(Not live yet)** HTTP 422, type `invalid_request_error`. Not in the v1 spec yet. A creator-data product has no published price yet, so the call is refused and nothing is billed. **Fix:** Try again after prices are published. ### `min_locations_not_met` **(Not live yet)** HTTP 422, type `invalid_request_error`. Not in the v1 spec yet. Creator data needs an account with enough counting locations and a prepaid balance. `blockers[]` and `next_action` say what is missing. Never billed. **Fix:** Do the `next_action`, then retry. ### `platform_not_supported` **(Not live yet)** HTTP 422, type `invalid_request_error`. Not in the v1 spec yet. The platform is not one CreatoRain holds. At launch: `instagram`, `tiktok`, `youtube`. Never billed. **Fix:** Send one of the supported platforms. ### `audience_not_available` **(Not live yet)** HTTP 422, type `invalid_request_error`. Not in the v1 spec yet. Audience fields are reserved in the schema, but no data is served for them yet. Never billed. **Fix:** Leave the audience fields out of the request. ## 429 Too many requests ### `rate_limited` HTTP 429, type `rate_limit_error`. Over the limit: 600 requests a minute per workspace, the onboarding create limit, or an address blocked after failed sign-ins. **Fix:** Wait `Retry-After` seconds, then retry. ### `quota_exceeded` **(Not live yet)** HTTP 429, type `rate_limit_error`. A usage quota for this period is used up. **Fix:** Wait for the next period, or contact support. ### `slow_down` HTTP 429, type `rate_limit_error`. An onboarding session was polled sooner than its `interval`. The interval grows by 5 seconds, up to 60. **Fix:** Wait `Retry-After` seconds between polls. ## 500 Server error ### `internal_error` HTTP 500, type `api_error`. Something failed on our side. The message never carries a cause. **Fix:** Retry with the same `Idempotency-Key`. Quote the `request_id` to support if it repeats. ## 503 Unavailable ### `service_unavailable` HTTP 503, type `api_error`. The service cannot answer right now. A concurrent write to the same locations also answers this. The bill preview answers it over 2,000 locations. **Fix:** Retry after `Retry-After` with the same key. ### `vendor_unavailable` **(Not live yet)** HTTP 503, type `api_error`. Not in the v1 spec yet. The outside source behind a vendor-backed creator-data field cannot answer right now. Never billed. **Fix:** Retry after `Retry-After`. # Changelog > Changes to the CreatoRain API, and the deprecation policy. The reference on this site is built from the API spec at commit `6555b098ea81`, copied on 2026-10-31. ## 2026-10-31 * First build of this docs site. * v1 spec: account, onboarding sessions, locations (one or a batch, with dry runs), visits, videos, bill preview. A spec diff of each release will be listed here. **(Not live yet)** ## Deprecation policy * Changes inside `/v1` are additive. Ignore fields you do not know. * A breaking change ships as `/v2`. `/v1` keeps working for 6 months after `/v2` ships. * A route being retired will send `Deprecation` and `Sunset` headers first. **(Not live yet)** # Coverage and capacity > Where CreatoRain has creators, how fast a store fills, and how monthly pacing works. Creators are local. A store fills as fast as nearby creators can visit. ## What you can read today * **`network.accepting`** on `GET /locations`: whether the network takes bookings now. * **`state`** on each store. `full_this_month` means the month’s videos are paced and the store waits for next month. `needs_hours` means the store has no bookable hours yet. * **`month`** on `GET /locations/{id}`: `planned`, `allowance`, `booked`, `visited`, `posted`, and `full` with `full_until`. ## Monthly pacing Each store gets its videos a month, spread over its own local month. When a month is full, the store shows `full_this_month` until the next month starts. ## Coverage check `GET /v1/coverage?address=` will answer whether a metro is served, and a first-visit estimate, before you add a store. **(Not live yet)** A store in a metro CreatoRain does not serve will be refused with `422 metro_not_served`. **(Not live yet)** # Creator data > Search and enrich public creator profiles, priced per result in USD. Privacy and opt-out. Not live yet Creator data is not live yet. None of these calls is in the v1 spec today. This page describes it as designed. Creator data is the API’s second product. It reads public creator profiles: their stats, bio and links. ## Calls (as designed) * `POST /v1/creators/search` and `POST /v1/creators/similar`: find creators. Search is free, up to a monthly ceiling. * `POST /v1/creators/enrich/handle` and `POST /v1/creators/enrich/email`: read one creator’s full profile. * `GET /v1/creators/{id}/posts`: a creator’s posts, by page. Each billed call is priced per result, in USD, from your [balance](https://docs.creatorain.com/pricing/wallet/). See [Prices](https://docs.creatorain.com/pricing/). ## Who can buy it Any account with a saved card and a paid top-up. Usage ceilings and the API terms apply. ## What is exposed Only what the creator published: profile and post numbers, bio and links. Contact emails come later, and only ones we can show are public. Never exposed: private emails, street addresses, or personal traits such as gender or ethnicity. ## Opt-out A creator can hide their profile from the data API: * on the creator portal, * on the www opt-out page, * or by email to . An opt-out is applied within one business day. Opting out of the data API does not unsubscribe a creator from CreatoRain’s own outreach. ## Webhooks carry no creator data Data job events hold ids, status and counts only. # Orders > Website, budget per video and total videos in. Finished posted videos out. Not live yet Orders are not live yet. None of these calls is in the v1 spec today. This page describes them as designed. An order is the shortest path: give your website, an average budget per video, and how many videos you need in total. CreatoRain returns finished, posted creator videos. ## How it works 1. `POST /v1/orders` with `website`, `average_budget_per_video_cents` and `total_videos`. CreatoRain finds your stores from the site. 2. The answer is a **quote**: options, a schedule per store, and a time range to finish. Never a single date. 3. `POST /v1/orders/{id}/confirm` writes the stores. It does not charge. 4. Fund it with a top-up. The order then schedules visits. 5. `GET /v1/orders/{id}` shows progress. `GET /v1/orders/{id}/videos` lists the finished videos. ## States `quoted` → `awaiting_funds` → `scheduling` → `in_production` → `delivered`. An order can also end `partially_delivered`, `cancelled`, `refunded` or `expired`. A quote expires after 24 hours. Low balance and capacity are **blockers** on the order, not states. Follow `next_action`. ## Rules * The website decides **where**, never **which creators**. A creator field is `400 customization_not_supported`. * The total stays at or under budget × count. * A finished video is the creator’s own post. You may repost, link and embed it with credit to the creator. # Rate limits > 600 requests a minute per workspace, the headers that report it, and how to back off. ## The limit **600 requests a minute per workspace**, counted across every server that answers. Each answer reports where you stand: | Header | Meaning | | --------------------- | ----------------------------------- | | `RateLimit-Limit` | Requests allowed this minute (600). | | `RateLimit-Remaining` | Requests left this minute. | | `RateLimit-Reset` | Seconds until the window resets. | Over the limit: `429 rate_limited` with `Retry-After` (at least 1 second). Wait that long, then retry with the same `Idempotency-Key`. ## Other limits * **Failed sign-ins:** 20 failed authentications from one address within a minute block that address for 15 minutes. * **Onboarding sessions:** 5 an hour per address, plus a global per-minute ceiling. * **Polling a session:** sooner than its `interval` is `429 slow_down`. The interval grows by 5 seconds, up to 60. ## Good habits * Page with `limit` up to 200 instead of many small calls. * Back off on `429`. Do not retry in a tight loop. * Use [webhooks](https://docs.creatorain.com/guides/webhooks/) instead of polling, once they are live. ## Creator data quotas Creator data will have its own monthly ceilings, answered with `429 quota_exceeded`. **(Not live yet)** # States and blockers > Account status, location states, blockers and next_action. An agent should not parse a state machine. Read `state` and `blockers`, and follow `next_action`. ## Account status `GET /account` returns `status`: | Status | Meaning | | ------------------ | --------------------------------- | | `awaiting_payment` | No payment yet. | | `active` | Running. | | `past_due` | A payment failed. | | `paused` | The client paused all production. | | `stopped` | Closed. | It also returns `counting_locations`, `min_locations` and `max_locations`. Read them; do not hard-code them. ## Location state Each store has one `state`, the same one the app’s Network page shows: | State | Meaning | | ------------------ | ---------------------------------------------------- | | `on_hold` | Added by API. Waits for CreatoRain to release it. | | `awaiting_payment` | Waits for payment. | | `needs_hours` | Has no bookable hours. | | `full_this_month` | This month’s videos are paced. Waits for next month. | | `accepting` | Open to creators. `accepting: true`. | | `paused` | Paused by you. | | `payment_failed` | Paused by a failed payment or a dispute. | | `ended` | Ended. | `status` is the plain lifecycle: `active`, `paused` or `ended`. `held` is `true` while the API hold stands. ## Blockers `blockers` lists why something cannot move yet. * On a location create: `below_minimum` while `counting_locations` is under `min_locations`. * On an onboarding session: `live_key_requires_top_up`, `key_limit_reached`, `owner_changed`. ## next_action `next_action` names the one thing to do next, such as a top-up. Today it is `null` on the account until the features behind each state ship. **(Not live yet)** # Video production > Add stores to the CreatoRain Network, and read back visits, posted videos and the bill. This is the API’s main feature. You add your stores. CreatoRain recruits local food creators, books their visits, and they post real videos. Not live yet These calls are built. The API is not open on production yet. ## The flow 1. **Quote** a store with `POST /locations?dry_run=true`. 2. **Add** it with `POST /locations`, or 1 to 50 at once with `POST /locations/batch`. 3. The store starts **on hold**. CreatoRain releases it to recruiting. 4. **Watch** with `GET /locations/{id}`, `GET /visits` and `GET /videos`. 5. **Preview** the month with `GET /bill/preview`. ## Adding a store Required fields: `name`, `address` (one line, or `line1`, `city`, `state`), `videos_per_month`. Optional: `google_place_id`, `plan`, `opening_hours`, `signature_dishes`. * **`accepted_terms`** is required for a new or returning store. It is the network terms version the store accepted, the meal waiver included. Without it: `400 terms_not_accepted`. * **`Idempotency-Key`** is required. Without it: `400 idempotency_key_required`. * **Paid plan:** `videos_per_month` is 2 to 10, at the account’s locked price per video. * **Free plan:** exactly the free plan’s videos for its term, with no deposit. * **`plan`** left out means the account’s plan. Another plan is `422 package_not_available`. * There is no store maximum. ### You do not choose the creators CreatoRain chooses the creators. Any creator field (`min_followers`, `rules`, `approval_mode`, …) is `400 customization_not_supported`. It is never silently ignored. ### The deposit is a quote On the paid plan, `deposit.cents` quotes half of month one: videos a month × price per video ÷ 2. It is paid later at Checkout. **No API call charges it** (`deposit.charged: false`). ### Repeats and conflicts * The same place again answers `200` with `outcome: repeat` and the **stored** plan. A create never updates a store. * An ended store comes back with `201` and `outcome: revive`. * A place another team of your account holds is `409 location_already_in_network`. ### Batches are all or nothing `POST /locations/batch` takes 1 to 50 stores. If any item is refused, the answer is `400 batch_invalid`, every refused item is in `error.items` by index, and **nothing** is written. ## Reading back * **`GET /locations`**: every store, oldest first, with `state`, `held` and `accepting`. `network.accepting` says whether the network takes bookings at all. * **`GET /locations/{id}`**: adds `month`, this store-local month’s pace: `planned`, `booked`, `visited`, `posted`, `full`. * **`GET /visits`**: newest update first. Filter by `location`, `status`, `from`, `to`. Times are on the **store’s** clock. A visit can appear again on a later page, so dedupe on `id`. * **`GET /videos`**: newest first. `counted_on_bill` is `true` only for a video stated at its store. `stats` is `null` until the public post is first read. Creators appear by public handle only. ## The bill preview `GET /bill/preview?month=YYYY-MM` shows the month’s bill, one line per store, in cents. It never charges (`charged: false`). `total_cents` is `null` when a store has no locked price yet. Over 2,000 stores the answer is `503 service_unavailable` rather than a short bill. ## Stores and creators tell each other A `visit.booked` webhook will tell your system a creator is coming, so you can tell the store. **(Not live yet)** See [Webhooks](https://docs.creatorain.com/guides/webhooks/). # Webhooks > Signed event delivery to your HTTPS endpoint, retries, and the events list. Not live yet Webhooks on v1 are not live yet. This page describes them as designed. Until then, poll the reads. ## Endpoints * `POST /v1/webhook_endpoints` with `{url, events}`. The answer carries a `secret` (`whsec_...`), **once**. * `GET`, `PATCH`, `DELETE /v1/webhook_endpoints/{id}`. * `POST /v1/webhook_endpoints/{id}/rotate_secret`: the old secret stays valid for 24 hours. * `POST /v1/webhook_endpoints/{id}/test`: sends one `ping`. * `GET /v1/events`: a poll fallback, 30 days back. The URL must be `https:` on port 443, on a public address. Redirects count as a failure. ## Envelope ```json { "id": "evt_...", "type": "visit.booked", "created": 1793000000, "livemode": true, "account_id": "acct_...", "data": { "object": {} } } ``` ## Signature Each delivery carries one header: ```http CreatoRain-Signature: t=,v1= ``` Check it with your endpoint secret. Refuse a timestamp more than 300 seconds old. During a secret rotation, two `v1=` values are sent. ## Retries A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2, 6 and 12 hours, then 24 hours twice: about 72 hours in all. After 3 days of failures the endpoint is disabled, with a `webhook_endpoint.disabled` event and a banner in the app. Order is not guaranteed. Dedupe on `id`. ## Events * **Locations:** `location.created`, `location.paused`, `location.resumed`, `location.terminated`. * **Production:** `visit.booked`, `visit.rescheduled`, `visit.cancelled`, `visit.completed`, `visit.no_show`, `video.posted`, `video.billed`, `video.taken_down`, `video.stats_updated`. * **Money:** `balance.topped_up`, `balance.top_up_failed`, `balance.low`, `balance.depleted`, `balance.refunded`, `balance.credited`, `balance.disputed`. * **Account:** `api_key.created`, `api_key.revoked`, `webhook_endpoint.disabled`. `visit.booked` is how your system learns a creator is coming, so you can tell the store. # Partner API > The API a POS or ordering platform uses to enrol its merchants' stores with CreatoRain. The Partner API is a separate surface from v1. A POS or ordering platform uses it to enrol its merchants’ stores, then read their reservations, published content and monthly billing. It is live for signed partners. It is not self-serve: CreatoRain issues each partner a key. ## Hosts | Mode | Host | | ------------------------------ | ------------------------------------------- | | Production | `https://data.creatorain.com/partner/v1` | | Sandbox, for integration tests | `https://datadev.creatorain.com/partner/v1` | ## Authentication One long-lived key per partner, sent as `Authorization: Bearer `. Keys look like `crp_live_...` on production and `crp_test_...` elsewhere. * The header is `Authorization` on every route. There is no `x-api-key` header. A key sent in one is not read, and the answer is `401 unauthorized`. * A key is scoped to one account and one campaign. It cannot read another customer’s data. * A key may carry an IP allowlist. Another address is `403 forbidden_ip`. ## Errors ```json { "error": { "code": "location_already_exists", "message": "...", "field": "partner_location_id" } } ``` Branch on `code`, never on `message`. This envelope is frozen for partners. It differs from v1’s. ## Rate limit 600 requests a minute per key by default. Over it: `429 rate_limited`, with `RateLimit-*` headers. ## Reference The [Partner reference](https://docs.creatorain.com/partner-api/reference/) is generated from the partner spec. The raw spec is at [`/partner-openapi.json`](https://docs.creatorain.com/partner-openapi.json). # Prices > API prices in US dollars, per call and per 1,000, from one balance. No credits to convert. One balance pays for videos and API calls. Prices are in US dollars. No monthly fee. No credits to convert. **Prices are published at launch.** They will appear here, read from the same reviewed snapshot as the www pricing page. ## How the numbers get here Prices are set by CreatoRain and served by `GET /v1/prices`. A reviewed snapshot of that answer feeds this page and the www pricing page. No price is typed into a page. **(Not live yet)** A product with no published price is left out, never shown as a dash. ## What you are never billed for * A creator not found. * An empty page. * A re-read of the same creator within 30 days. * A replayed `Idempotency-Key`. * Video-production reads (account, locations, visits, videos), dry runs and the bill preview. ## What each call cost Every billed call will return a `cost` object, `{amount_micros, currency: "USD"}`, and a `CreatoRain-Cost` header. Usage is priced in micro-dollars (1 USD = 1,000,000 micros), so a price per 1,000 is exact. **(Not live yet)** ## Next * [Wallet](https://docs.creatorain.com/pricing/wallet/): the one balance. * [Top-ups, holds and refunds](https://docs.creatorain.com/pricing/top-ups-holds-refunds/) * [Spend limits](https://docs.creatorain.com/pricing/spend-limits/) # Spend limits > Daily and monthly limits, the low-balance alert, and what happens at the limit. Not live yet Spend limits are not live yet. This page describes them as designed. You can cap what the API spends. * **Daily** and **monthly** limits, set in the app. * A **low-balance threshold**. When “$X left” falls below it, you get a `balance.low` event and a banner in the app. It is your own setting, and it starts empty. ## Lower by API, raise in the app `PATCH /v1/balance/settings` can **lower** a limit. It can never raise one. A raise by API answers `403 limit_raise_requires_dashboard`, with a link to the app. So a leaked key cannot lift your caps. ## At the limit What happens depends on the product. * **Creator data.** A billed call that would pass the daily or monthly data limit is refused. It answers `402 spend_limit_reached`, and nothing is charged. * **Video production.** Nothing is refused. A video slot that would pass the daily limit or the monthly commit limit does not open. The store waits and shows `awaiting_payment` until the limit has room. See [Errors](https://docs.creatorain.com/errors/#spend_limit_reached). # Top-ups, holds and refunds > Adding money, how a video holds its price, how API usage is booked, refunds and statements. Not live yet Top-ups, holds, refunds and statements are not live yet. This page describes them as designed. ## Top-ups * Top up in the app, with a card, by Stripe Checkout. * By API: `POST /v1/balance/top_ups` returns a `checkout_url`. A human finishes the payment. * The smallest top-up is set by CreatoRain and published with the [prices](https://docs.creatorain.com/pricing/). It is a payment floor, not a spend minimum. * Each top-up shows a receipt link on the Balance page. ## Holds When a creator visit is booked, a **hold** sets aside the store’s locked price per video. When the video goes live, the hold becomes a charge. If the visit does not happen, the hold is released. Held money still belongs to you. It just is not in “$X left”. ## API usage Each billed call is priced in micro-dollars. Usage is written to your statement in small batches, and at the end of each UTC day. The rest carries over. No call is rounded up to a whole cent. ## Refunds * **Cash** is refundable on request, less the card fee. Or wait 30 days or more and get it back in full. * **Granted** money is never refunded. * Nothing expires. ## Statements A monthly statement lists the opening balance, top-ups, video charges, API usage, grants, refunds and the closing balance. **(Not live yet)** ## Auto-recharge Top up automatically when the balance falls below a level you set. **(Not live yet)** # Wallet > One USD balance, shared by creator videos and API calls. You see "$X left". No credits. Not live yet The wallet is not live yet. This page describes it as designed. Your workspace has **one balance, in US dollars**. Creator videos and API calls both draw from it. The app shows it as **“$X left”**. There are no credits and no exchange rate. ## What “$X left” means > left = cash + granted − held − usage not yet booked * **Cash** is money you topped up. It never expires. * **Granted** is money CreatoRain gave you. It shows as “Granted by CreatoRain (not refundable)”. Granted money is spent first. * **Held** is money set aside for videos already booked. See [holds](https://docs.creatorain.com/pricing/top-ups-holds-refunds/#holds). * **Usage not yet booked** is API usage priced but not yet written to your statement. ## $5 to start A new account gets **$5, once**, when it saves a card. It is granted money: not refundable, and one per card. **(Not live yet)** ## When the balance is below zero Stores that joined through the app’s Join flow keep running if the balance runs out. The app then says “You owe $Y. It goes on your card at month end.” Stores added by API need enough balance to open each video slot. If the balance is short, new video slots wait. Each store shows `awaiting_payment`, and the account carries the blocker `insufficient_balance`. A batch create with `require_funded: true` answers `402 insufficient_balance` instead. **(Not live yet)** ## Reading it by API Not live yet * `GET /v1/balance`: `available_cents`, `cash_cents`, `granted_cents`, `held_cents`. * `GET /v1/balance/entries`: every money event, one line each. * `GET /v1/balance/holds`: open holds. Amounts are integer cents in USD. ## Who sees it Owners and billing roles see the balance and top up. A plain member does not. # SDKs and tools > The OpenAPI spec, TypeScript and Python SDKs, and the CreatoRain MCP server for AI agents. ## OpenAPI spec The v1 spec is public here: [`/openapi.json`](https://docs.creatorain.com/openapi.json). It is the same file this site’s reference is generated from. Feed it to any OpenAPI tool. The Partner API spec is at [`/partner-openapi.json`](https://docs.creatorain.com/partner-openapi.json). ## TypeScript A TypeScript client generated from the spec, on npm. **(Not live yet)** ## Python A Python client generated from the spec, on PyPI. **(Not live yet)** ## MCP server An MCP server for AI agents at `https://api.creatorain.com/mcp`, with your API key. It will also search these docs. **(Not live yet)** ## For agents today * [llms.txt](https://docs.creatorain.com/llms.txt): an index, with instructions for agents. * [llms-full.txt](https://docs.creatorain.com/llms-full.txt): every guide in one file. * Every page has a markdown copy: add `.md` to its path. # Status > Where to see whether the CreatoRain API is up. Not live yet There is no public status page yet, and no `GET /v1/health`. This page will link to them. Until then: * Every answer carries a `Request-Id`. Quote it when you report a problem. * A `503 service_unavailable` with `Retry-After` is safe to retry with the same `Idempotency-Key`. * Report a problem to . # API reference Every generated endpoint page, v1 then Partner API. ## v1 API reference overview **Not live yet:** the v1 API and its hosts are not open. See [Sandbox](https://docs.creatorain.com/get-started/sandbox/). ### CreatoRain API 1.0.0 A client’s own server or AI agent, holding a key for ONE workspace, uses this API to run restaurant video production. Every response carries a `Request-Id` header; every error has the envelope `{error:{type, code, message, field?, doc_url, request_id}}`. Rate limit: 600 requests a minute per workspace, across every server that answers. Above it, `429 rate_limited` with `Retry-After`. Twenty failed authentications (missing or unknown key) from one address within a minute block that address for 15 minutes. Information - OpenAPI version: `3.0.3` ### Operations GET [/account](https://docs.creatorain.com/reference/operations/getaccount/) POST [/onboarding\_sessions](https://docs.creatorain.com/reference/operations/createonboardingsession/) GET [/onboarding\_sessions/{id}](https://docs.creatorain.com/reference/operations/getonboardingsession/) GET [/locations](https://docs.creatorain.com/reference/operations/listlocations/) POST [/locations](https://docs.creatorain.com/reference/operations/createlocation/) POST [/locations/batch](https://docs.creatorain.com/reference/operations/createlocationsbatch/) GET [/locations/{id}](https://docs.creatorain.com/reference/operations/getlocation/) GET [/visits](https://docs.creatorain.com/reference/operations/listvisits/) GET [/videos](https://docs.creatorain.com/reference/operations/listvideos/) GET [/bill/preview](https://docs.creatorain.com/reference/operations/getbillpreview/) ### Authentication #### bearerAuth Authorization: Bearer crp\_live\_… or crp\_rk\_live\_… (live), crp\_test\_… or crp\_rk\_test\_… (sandbox). **Security scheme type:** http #### sessionSecret Authorization: Bearer crp\_obs\_… (the session\_secret from POST /onboarding\_sessions). Polls one session only. **Security scheme type:** http Source: https://docs.creatorain.com/reference/ (markdown: https://docs.creatorain.com/reference.md) ## Add one location to the CreatoRain Network **Not live yet:** the v1 API and its hosts are not open. See [Sandbox](https://docs.creatorain.com/get-started/sandbox/). POST /locations Select code sampleFetchcURL ```js const url = 'https://api.creatorain.com/v1/locations?dry_run=false'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"name":"Sexy Crab Duluth","address":"2416 Pleasant Hill Rd, Duluth, GA 30096","google_place_id":"example","plan":"paid","videos_per_month":4,"accepted_terms":"network-2026-10","opening_hours":{},"signature_dishes":[{"name":"example"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url 'https://api.creatorain.com/v1/locations?dry_run=false' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "name": "Sexy Crab Duluth", "address": "2416 Pleasant Hill Rd, Duluth, GA 30096", "google_place_id": "example", "plan": "paid", "videos_per_month": 4, "accepted_terms": "network-2026-10", "opening_hours": {}, "signature_dishes": [ { "name": "example" } ] }' ``` - Live (crp\_live\_ keys) - Sandbox (crp\_test\_ keys) Scope `locations:write`. The store is created ON HOLD (`state: on_hold`): nothing recruits or books it until CreatoRain releases it. The plan is the account’s: on the paid plan `videos_per_month` is 2 to 10 at the locked price per video, and `deposit` quotes the half of month one (paid later at Checkout, never charged here); on the free plan it is exactly the free plan’s videos for its term, with no deposit. There is no store maximum. Creator selection is CreatoRain’s: a creator field (`min_followers`, `rules`, `approval_mode`, …) is `400 customization_not_supported`. The same place again answers `200` with `outcome: repeat` and the STORED plan (a create never updates one); a place another team of this account holds is `409 location_already_in_network`. ### Authorizations - **[bearerAuth](https://docs.creatorain.com/reference/#bearerauth)** ### Parameters #### Header Parameters **Idempotency-Key** required string \>= 1 characters <= 255 characters /^\[\\x21-\\x7E\]+$/ As `Idempotency-Key`, and required here (a location create). Without it the answer is `400 idempotency_key_required`. A dry run needs one too: it writes no store row; the Idempotency-Key is still stored. #### Query Parameters **dry\_run** boolean `true` validates and quotes: the same refusals as a live call, and writes no store row; the Idempotency-Key is still stored. Ids are null. ### Request Bodyrequired Media typeapplication/json object **name** required string \>= 1 characters <= 300 characters #### Example ``` Sexy Crab Duluth ``` **address** required One of: - [string](#tab-panel-0-0) - [object](#tab-panel-0-1) string \>= 5 characters <= 400 characters #### Example ``` 2416 Pleasant Hill Rd, Duluth, GA 30096 ``` object **line1** required string <= 300 characters **city** required string <= 120 characters **state** required string <= 120 characters **postal\_code** string nullable <= 40 characters **country** string nullable <= 120 characters **google\_place\_id** string nullable <= 300 characters **plan** Absent means the account’s plan; another plan is 422 package\_not\_available. string Allowed values: paid free **videos\_per\_month** required Paid: 2 to 10. Free: exactly the free plan’s videos. Otherwise 400 videos\_per\_month\_out\_of\_range. integer #### Example ```json 4 ``` **accepted\_terms** The network terms version accepted string nullable /^\[a-z0-9\]\[a-z0-9.-\]{2,59}$/ #### Example ``` network-2026-10 ``` **opening\_hours** The store’s week object **signature\_dishes** Array <= 50 items One of: - [string](#tab-panel-1-0) - [object](#tab-panel-1-1) string <= 300 characters object **name** required string <= 300 characters ### Responses #### 200 A repeat of a live store (nothing written), or a dry run. Media typeapplication/json object **object** required string Allowed values: location **id** required Null on a dry run. string nullable **outcome** required string Allowed values: create repeat revive **livemode** required boolean **name** required string nullable **address** required string nullable **plan** required string Allowed values: paid free **videos\_per\_month** required integer nullable **term\_months** required Free: the free term. Paid: null, until stopped. integer nullable **price\_per\_video\_cents** required integer nullable **currency** required string Allowed values: USD **deposit** required object **cents** required The half of month one: videos\_per\_month x price\_per\_video\_cents / 2. Free: 0. integer nullable **charged** required Never charged by this call. boolean **state** required The network state; null on a dry run. string nullable **dry\_run** required boolean **account** required object **counting\_locations** required Live stores of this account after the call (a dry run - as it would be). integer **min\_locations** required integer **blockers** required Below\_minimum while counting\_locations is under min\_locations. Array ##### Example ```json { "object": "location", "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e", "outcome": "create", "plan": "paid", "price_per_video_cents": 30000, "currency": "USD", "deposit": { "charged": false }, "state": "on_hold", "account": { "min_locations": 3 } } ``` ##### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Idempotent-Replayed** string Allowed values: true True when this answer is the stored response to an earlier request with the same Idempotency-Key. #### 201 Created, or an ended store brought back (`outcome: revive`); on hold either way. Media typeapplication/json object **object** required string Allowed values: location **id** required Null on a dry run. string nullable **outcome** required string Allowed values: create repeat revive **livemode** required boolean **name** required string nullable **address** required string nullable **plan** required string Allowed values: paid free **videos\_per\_month** required integer nullable **term\_months** required Free: the free term. Paid: null, until stopped. integer nullable **price\_per\_video\_cents** required integer nullable **currency** required string Allowed values: USD **deposit** required object **cents** required The half of month one: videos\_per\_month x price\_per\_video\_cents / 2. Free: 0. integer nullable **charged** required Never charged by this call. boolean **state** required The network state; null on a dry run. string nullable **dry\_run** required boolean **account** required object **counting\_locations** required Live stores of this account after the call (a dry run - as it would be). integer **min\_locations** required integer **blockers** required Below\_minimum while counting\_locations is under min\_locations. Array ##### Example ```json { "object": "location", "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e", "outcome": "create", "plan": "paid", "price_per_video_cents": 30000, "currency": "USD", "deposit": { "charged": false }, "state": "on_hold", "account": { "min_locations": 3 } } ``` ##### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Idempotent-Replayed** string Allowed values: true True when this answer is the stored response to an earlier request with the same Idempotency-Key. #### 400 Parameter\_invalid (with `field`) or invalid\_json. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array