Skip to content
CreatoRainCreatoRain API
Not live yet: the v1 API and its hosts are not open. See Sandbox.

Open an onboarding session (no key)

POST
/onboarding_sessions
curl --request POST \
  --url https://api.creatorain.com/v1/onboarding_sessions \
  --header 'Content-Type: application/json' \
  --data '{ "client_name": "example", "requested_scopes": [ "read" ], "requested_livemode": true }'

No API key: this is how an agent without one starts. Show the human user_code and url. session_secret is returned ONCE and is the only way to poll; store it like a key. The requested scopes and mode are a request only: the approving human decides. 5 sessions an hour per address, and a global per-minute ceiling, then 429 rate_limited with Retry-After.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
client_name

Shown to the human as an unverified name.

string
nullable <= 100 characters
requested_scopes
Array<string>
nullable
Allowed values: read samples:read locations:write balance:write creators:read webhooks:write
requested_livemode
boolean
nullable

Responses

Section titled “Responses”

201

Section titled “201”

The session. Poll it every interval seconds until it is approved, denied or expired.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed values: onboarding_session
status
required
string
Allowed values: pending
url
required
string format: uri
user_code
required

Eight letters; the human types it in the app.

string
session_secret
required

Shown once. The only way to poll this session.

string
expires_at
required

15 minutes after creation.

string format: date-time
interval
required

Seconds between polls.

integer

Example 

{
  "id": "obs_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e",
  "object": "onboarding_session",
  "status": "pending",
  "url": "https://app.creatorain.com/settings/api/connect?code=BCDF-GHJK",
  "user_code": "BCDF-GHJK",
  "session_secret": "crp_obs_...",
  "interval": 5
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

Cache-Control
string
Allowed values: no-store

No-store. The answer may carry a secret.

400

Section titled “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<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

429

Section titled “429”

Rate_limited (600 a minute per workspace, an onboarding create limit, or an address blocked after failed authentication), or slow_down (an onboarding session polled too fast).

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<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

Retry-After
integer
>= 1

Seconds to wait before retrying (at least 1).

500

Section titled “500”

Internal_error (500) or service_unavailable (503). The message never carries a cause.

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<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

503

Section titled “503”

Internal_error (500) or service_unavailable (503). The message never carries a cause.

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<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.