Optimly Onboarding API

The Onboarding API from Optimly — 7 operation(s) for onboarding.

GitHub OpenAPI

Operations 7

POST /api/onboarding/website Start Onboarding #
GET /api/onboarding/claim-preview Claim Preview #
POST /api/onboarding/{brand_id}/finish Finish Onboarding Route #
GET /api/onboarding/{brand_id}/status Onboarding Status #
PUT /api/onboarding/{brand_id}/interview/answers/{question_id} Save Interview Answer Route #
POST /api/onboarding/{brand_id}/interview/complete Complete Interview Route #
POST /api/onboarding/{brand_id}/interview/skip Skip Interview Route #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/optimly-ai:optimly-ai-onboarding-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

optimly-ai-onboarding-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Optimly Onboarding API
  version: 0.1.0
tags:
- name: Onboarding
paths:
  /api/onboarding/website:
    post:
      summary: Start Onboarding
      description: 'Ownership-gated create/claim (the acting user''s

        verified individual business email at the domain is required; a claim additionally requires

        the unclaimed brand''s canonical domain to match) → draft brand → enqueue

        `onboarding.scrape`, for creates AND claims (**** Mark

        a claimed brand runs the same onboarding flow as an added

        one); `{brand_id, claimed, resumed}` returns immediately. `resumed` is

        true when the org already had a non-archived brand at this URL, so the

        SPA picks the existing draft back up instead of starting a duplicate.'
      operationId: start_onboarding_api_onboarding_website_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Start Onboarding Api Onboarding Website Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/claim-preview:
    get:
      summary: Claim Preview
      description: 'The claim prefill: the brand being

        claimed already carries its domain, so making the user re-type the URL

        was redundant — resolve the carried token exactly as the claim shortcut

        will (the brand id first, the legacy page-slug form as fallback → an

        unclaimed brand) and hand the SPA the target''s URL of record. 404 when

        the token resolves nothing or the target is already claimed: the SPA

        blocks the explicit claim until the visitor chooses a different flow.'
      operationId: claim_preview_api_onboarding_claim_preview_get
      parameters:
      - name: claim_slug
        in: query
        required: true
        schema:
          type: string
          title: Claim Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Claim Preview Api Onboarding Claim Preview Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/{brand_id}/finish:
    post:
      summary: Finish Onboarding Route
      description: 'Publish the quick-start answers as the first vault version and queue the

        first report.


        The draft merge lives in `services/onboarding_finish.py`: the draft is not

        a version, so a four-field payload cannot be published directly without

        blanking the other prefilled sections. Publish + enqueue share this

        transaction, so a dropped connection cannot leave a published vault with no

        report — the exact failure this flow exists to prevent.


        Returns `{version, run_queued, gate, reason}`. A closed gate or an empty

        profile is a 200 with `run_queued: false`, not an error: the profile was

        saved successfully, and the client routes the user to the right remedy.'
      operationId: finish_onboarding_route_api_onboarding__brand_id__finish_post
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Finish Onboarding Route Api Onboarding  Brand Id  Finish Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/{brand_id}/status:
    get:
      summary: Onboarding Status
      description: 'Prefill progress: `prefill_status`, vault completeness off

        the draft (or the active version once published), and whether the report

        button is live (`can_generate_report` — an active vault version exists).

        `interview` is the enrolled attempt''s phase/questions/answers/result —

        None for a brand created before the interview shipped (no row was ever

        created). Reading never starts a new attempt.'
      operationId: onboarding_status_api_onboarding__brand_id__status_get
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Onboarding Status Api Onboarding  Brand Id  Status Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/{brand_id}/interview/answers/{question_id}:
    put:
      summary: Save Interview Answer Route
      description: 'Save or revise ONE answer against the frozen batch (spec §6): the

        choice/skip/Other text is validated against the saved question — never a

        browser-supplied definition — and `expected_revision` is the

        compare-and-set token; a stale revision is a 409, an identical retry is a

        no-op `{revision, changed: false}` that does not bump it.'
      operationId: save_interview_answer_route_api_onboarding__brand_id__interview_answers__question_id__put
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      - name: question_id
        in: path
        required: true
        schema:
          type: string
          title: Question Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Save Interview Answer Route Api Onboarding  Brand Id  Interview Answers  Question Id  Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/{brand_id}/interview/complete:
    post:
      summary: Complete Interview Route
      description: 'The final action: every question answered/skipped/Not-sure →

        `finalizing` + the build job on its stable dedupe key. Repeated submits

        return the current progress/result without a second enqueue; a completed

        attempt returns its saved result idempotently.'
      operationId: complete_interview_route_api_onboarding__brand_id__interview_complete_post
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Complete Interview Route Api Onboarding  Brand Id  Interview Complete Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
  /api/onboarding/{brand_id}/interview/skip:
    post:
      summary: Skip Interview Route
      description: 'Abandon an unfinished attempt: terminal `skipped`, outstanding jobs

        fenced by the handlers'' status rechecks, and the client routes to the

        draft BrandVault editor. Never applicable to a completed interview (409);

        already-terminal rows return the same destination state as a no-op.'
      operationId: skip_interview_route_api_onboarding__brand_id__interview_skip_post
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Skip Interview Route Api Onboarding  Brand Id  Interview Skip Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Onboarding
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError