generated: '2026-08-09'
method: searched
source: https://developers.ceros.com/guides/getting-started
docs:
- https://developers.ceros.com/guides/getting-started
- https://developers.ceros.com/guides/versioning
- https://developers.ceros.com/api/public/ceros-public-api
derived_from:
- openapi/ceros-public-api-openapi.yml
- openapi/ceros-public-api-2026-02-25-openapi.yml
provider: Ceros
api: Ceros Public API
base_url: https://rest.ceros.com
authentication:
  style: bearer-api-key
  scheme: 'http / bearer'
  bearer_format: API_KEY
  header: 'Authorization: Bearer YOUR_API_KEY'
  key_issuance: Generated by the customer from Ceros account settings.
  oauth: false
  note: >-
    A single long-lived account API key. No OAuth, no scopes, no per-key permission model is
    published — the key inherits whatever the account can see. Docs warn to treat it as a secret
    and keep it out of client-side code.
  see_also: authentication/ceros-authentication.yml
versioning:
  style: dated-snapshot
  header: x-ceros-api-version
  example_value: 2026-05-28-09-00
  format: YYYY-MM-DD-HH-MM
  default_when_omitted: latest version
  pinning_guidance: >-
    "Production integrations should pin an explicit version so upgrades happen on your schedule,
    not ours."
  breaking_change_policy: >-
    A new dated version is cut "when a change would otherwise break existing integrations".
    Shipped versions are permanent snapshots and do not change.
  url_versioning: false
  see_also: lifecycle/ceros-lifecycle.yml
required_headers:
- name: Authorization
  value: 'Bearer YOUR_API_KEY'
  required: true
- name: x-ceros-api-version
  value: '2026-05-28-09-00'
  required: false
  note: Recommended for production; omitting it floats you onto the latest version.
idempotency:
  supported: false
  note: >-
    No idempotency key, no retry-safety guidance and no request-deduplication mechanism is
    documented anywhere on developers.ceros.com. The non-idempotent writes that existed in
    2026-02-25-12-00 (createPage, duplicatePage, batchUpdatePage, applyPageTemplate) shipped
    without one. Recorded as absent — no Idempotency pointer is emitted for this provider.
pagination:
  style: page-number
  applies_to: [listFolderExperiences]
  params:
  - name: page
    description: Page of results to return, 1-based. Defaults to 1.
  - name: pageSize
    description: Results per page, capped at 50. Defaults to 50.
  envelope:
    self: Canonical URL of this page of results
    resourceType: Type of resource contained in `data`
    data: Resources on the current page
    paging:
      total: Total number of matching resources
      page: Current page number, 1-based
      pages: Total number of pages available
      pageSize: Maximum resources returned per page
      previous: URL of the previous page, absent on the first page
      next: URL of the next page, absent on the last page
  response_fields: >-
    HATEOAS-ish — `paging.next` and `paging.previous` are absolute URLs, so a client can walk the
    set without reconstructing query strings. No cursor/token pagination anywhere in the surface.
  note_envelope: >-
    Only listFolderExperiences uses this envelope. getFolderTree returns a bare `resources[]`,
    getAllExperiencePages a bare `data[]`, and getEmbedCodes/getCurrentAccount return flat
    objects — the surface has no single response envelope.
  note: getFolderTree is bounded by `depth` (default 2, 0 = all levels) rather than paged.
expansion:
  supported: true
  style: comma-separated expand parameter
  applies_to: [getFolderTree]
  param: expand
  values: [experiences, members]
  rationale: >-
    "Experiences and member counts are expensive and excluded by default — request them with
    expand=experiences,members."
filtering_and_sorting:
  applies_to: [listFolderExperiences]
  search:
    param: search
    description: Filter experiences by name.
  sort:
    param: sort
    default: last_created
    values: [alphabetical_a_to_z, alphabetical_z_to_a, last_created, last_updated, last_published]
    invalid_value_behaviour: 400
  scoping:
    param: folder
    applies_to: [getFolderTree]
    description: Restrict the tree to one branch, returning that folder plus descendants and its ancestors for structure.
identifiers:
  style: opaque resource ids
  names: [accountResourceId, experienceResourceId, folderResourceId, pageId]
  discovery_flow: >-
    getCurrentAccount returns accountResourceId -> getFolderTree returns folderResourceId ->
    listFolderExperiences returns experienceResourceId -> getAllExperiencePages returns pageId.
  prefixes: none published
  see_also: data-model/ceros-data-model.yml
errors:
  envelope: 'errors[] with message + optional cause[] (400/401/404); message-only (403)'
  rfc9457: false
  see_also: errors/ceros-problem-types.yml
request_tracing:
  request_id_header: none published
  note: No correlation/request-id header is documented, and none is echoed on the 401 observed live.
rate_limiting:
  published: false
  headers: none published
  documented_429: false
  note: >-
    No rate limit, quota, burst policy or 429 response is documented on any operation or in the
    getting-started guide.
content_type:
  request: application/json
  response: application/json
  note: >-
    Query parameters in the published spec are unusually declared with a `content:
    application/json` wrapper rather than a plain `schema`, which is legal OpenAPI but will
    surprise most generators.
sandbox:
  published: false
  note: No test mode, sandbox host, test keys or fixture tooling is documented.