Optimly Brands API

The Brands API from Optimly — 10 operation(s) for brands.

GitHub OpenAPI

Operations 14

GET /api/brands List Brands #
POST /api/brands Create Brand #
PATCH /api/brands/{brand_id} Patch Brand #
GET /api/brands/{brand_id}/attribution Get Attribution #
GET /api/brands/{brand_id}/home Get Home #
GET /api/brands/{brand_id}/vault Get Vault #
GET /api/brands/{brand_id}/vault/versions List Versions #
POST /api/brands/{brand_id}/vault/versions Publish New Version #
GET /api/brands/{brand_id}/vault/versions/{version} Get Version #
GET /api/brands/{brand_id}/reports List Reports #
POST /api/brands/{brand_id}/reports Click Generate Report #
GET /api/brands/{brand_id}/recommendations List Brand Recommendations #
GET /api/v2/brands List Keyed Brands #
POST /api/v2/brands Create Keyed Brand #

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-brands-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-brands-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Optimly Brands API
  version: 0.1.0
tags:
- name: Brands
paths:
  /api/brands:
    get:
      summary: List Brands
      operationId: list_brands_api_brands_get
      parameters:
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Brands Api Brands Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
    post:
      summary: Create Brand
      operationId: create_brand_api_brands_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Brand Api Brands Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}:
    patch:
      summary: Patch Brand
      operationId: patch_brand_api_brands__brand_id__patch
      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 Patch Brand Api Brands  Brand Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/attribution:
    get:
      summary: Get Attribution
      operationId: get_attribution_api_brands__brand_id__attribution_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 Get Attribution Api Brands  Brand Id  Attribution Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/home:
    get:
      summary: Get Home
      description: 'One round trip for the landing page: everything the ladder needs,

        nothing it does not.'
      operationId: get_home_api_brands__brand_id__home_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 Get Home Api Brands  Brand Id  Home Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/vault:
    get:
      summary: Get Vault
      operationId: get_vault_api_brands__brand_id__vault_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 Get Vault Api Brands  Brand Id  Vault Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/vault/versions:
    get:
      summary: List Versions
      operationId: list_versions_api_brands__brand_id__vault_versions_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 List Versions Api Brands  Brand Id  Vault Versions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
    post:
      summary: Publish New Version
      operationId: publish_new_version_api_brands__brand_id__vault_versions_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:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Publish New Version Api Brands  Brand Id  Vault Versions Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/vault/versions/{version}:
    get:
      summary: Get Version
      operationId: get_version_api_brands__brand_id__vault_versions__version__get
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Version Api Brands  Brand Id  Vault Versions  Version  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/reports:
    get:
      summary: List Reports
      operationId: list_reports_api_brands__brand_id__reports_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 List Reports Api Brands  Brand Id  Reports Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
    post:
      summary: Click Generate Report
      description: 'Click-generate — how a run starts, since nothing generates a report

        automatically (`spec/07` §1.6).


        Three distinct 409s, because each gate has a different remedy and the UI

        has to say which one bit: `vault_not_published` (save your profile),

        `report_budget_exhausted` (wait for the unlock, or upgrade), `vault_stale`

        (update your profile). **The rule is not restated here** — it is one call

        into `services/entitlement.py`, which the home screen and both endpoints

        share, so there is no second copy to drift.'
      operationId: click_generate_report_api_brands__brand_id__reports_post
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Click Generate Report Api Brands  Brand Id  Reports Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/brands/{brand_id}/recommendations:
    get:
      summary: List Brand Recommendations
      operationId: list_brand_recommendations_api_brands__brand_id__recommendations_get
      parameters:
      - name: brand_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Brand Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: effort
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Effort
      - name: days
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Brand Recommendations Api Brands  Brand Id  Recommendations Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
  /api/v2/brands:
    get:
      summary: List Keyed Brands
      description: 'Brand enumeration for org-scoped keys: every brand in

        the key''s org, ordered by name — the ids an `X-Optimly-Brand` selector

        accepts. A brand-scoped key sees its one brand (the selector is moot).'
      operationId: list_keyed_brands_api_v2_brands_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Keyed Brands Api V2 Brands Get
      tags:
      - Brands
    post:
      summary: Create Keyed Brand
      description: 'Create a brand in the key''s organization.


        Org-scoped keys only — a brand-scoped key already pins a brand and cannot

        create another. The key''s owner must be a **trusted user**: a credential has

        no live mailbox to prove domain ownership, so trust is the authorization.

        An exact canonical-URL match in the org returns that brand instead of

        creating a second one, with `created: false`. The site prefill scrape runs;

        the interactive interview and any report run do not.'
      operationId: create_keyed_brand_api_v2_brands_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 Create Keyed Brand Api V2 Brands Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Brands
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