upspring-ai Taxonomy API

openapi: 3.2.0
info:
  title: Upspring Public Taxonomy API
  version: 1.0.0
  description: 'A read-only REST API over Upspring''s external ad-intelligence corpus: ads, advertisers, and taxonomy, humanized into `{id,label}` dimension values with verbatim creative text — no video files, no LLM in the loop required on your end.


    **Estimates only.** Scale tiers (spend / traffic / sales) are **coarse estimates, never exact figures**. Spend is a modelled estimate; traffic and sales are third-party estimates surfaced only as tiers. This is competitive intelligence, **not a data feed** — the underlying numbers are not, and will not be, exposed.'
servers:
- url: https://public-api.upspring.ai
  description: This deployment
security:
- bearerAuth: []
tags:
- name: Taxonomy
paths:
  /v1/taxonomy/verticals:
    get:
      tags:
      - Taxonomy
      summary: List all verticals and their categories
      description: Look up valid `vertical=`/`category=` filter values used across every other endpoint.
      responses:
        '200':
          description: All verticals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerticalsResponse'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded for this key's tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Unexpected server-side failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getV1TaxonomyVerticals
      x-operation-id-source: derived
  /v1/taxonomy/verticals/{vertical}/categories:
    get:
      tags:
      - Taxonomy
      summary: Get a vertical's categories and dimension vocabularies
      description: Also returns the vertical-scoped Layer-2 dimension vocabularies (archetypes/personas) alongside global Layer-1 ones (hook archetype, mechanism, funnel stage, persuasion technique).
      parameters:
      - schema:
          type: string
          example: skincare
        required: true
        name: vertical
        in: path
      responses:
        '200':
          description: Vertical detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerticalCategoriesResponse'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Unrecognized vertical id (`public-api-vertical-not-found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded for this key's tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Unexpected server-side failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getV1TaxonomyVerticalsByVerticalCategories
      x-operation-id-source: derived
components:
  schemas:
    VerticalsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Vertical'
      required:
      - data
      additionalProperties: false
    VerticalCategoriesResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/VerticalDetail'
      required:
      - data
      additionalProperties: false
    Vertical:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
            required:
            - id
            - label
            additionalProperties: false
      required:
      - id
      - label
      - categories
      additionalProperties: false
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: public-api-ad-not-found
            message:
              type: string
            request_id:
              type: string
          required:
          - code
          - message
          - request_id
          additionalProperties: false
      required:
      - error
      additionalProperties: false
      description: 'Uniform error shape returned by every /v1 endpoint on failure. `code` is a stable, kebab-case machine-readable identifier safe to branch on; `message` is human-readable but not a stable contract; `request_id` correlates the response with server-side logs. Known `code` values:


        - `public-api-invalid-key` (401) — missing, malformed, or revoked API key.

        - `public-api-rate-limited` (429) — per-key rate limit exceeded; a `Retry-After` header is set (standard tier: 60/min, 5000/day).

        - `public-api-invalid-query` (400) — the query string doesn''t match the endpoint''s expected parameter shape, or names a specific invalid parameter value (e.g. an unknown `group_by` dimension) — the error `message` names the offending parameter.

        - `public-api-invalid-cursor` (400) — the `cursor` value is malformed.

        - `public-api-cursor-filter-mismatch` (400) — the `cursor` was minted for a different filter set than the one on this request; re-fetch the first (unpaginated) page instead of replaying a cursor across a filter change.

        - `public-api-cursor-out-of-range` (400) — the `cursor`''s decoded offset is past this endpoint''s browse ceiling (5000 rows); start over from an unpaginated request instead of replaying an out-of-range cursor.

        - `public-api-search-group-unsupported` (400) — `q` and `group_by` were both supplied on `GET /v1/ads`; they''re mutually exclusive.

        - `public-api-ad-not-found` (404), `public-api-advertiser-not-found` (404), `public-api-vertical-not-found` (404) — the id/slug in the path doesn''t exist.

        - `public-api-route-not-found` (404) — no route matches this `/v1` path (a typo''d or retired endpoint).

        - `public-api-internal-error` (500) — unexpected server-side failure.


        This list is NOT exhaustive: a small number of endpoints pass a handful of their own domain-level validation codes straight through unchanged rather than remapping them — e.g. `GET /v1/advertisers/{id}/compare/{otherId}` can return `compare-advertisers-same-advertiser` (400, comparing an advertiser against itself) or `compare-advertisers-unknown-advertiser` (404); `POST /v1/advertisers/{id}` can also 429 with its own daily new-advertiser limit code (distinct from the standard per-key rate limit above) or 502 if the request couldn''t be started. Treat any unrecognized `code` per its HTTP status and surface `message` to a human.'
    VerticalDetail:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
            required:
            - id
            - label
            additionalProperties: false
        dimensions:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                label:
                  type: string
              required:
              - id
              - label
              additionalProperties: false
      required:
      - id
      - label
      - categories
      - dimensions
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: upk_...
      description: 'A key minted by ops via scripts/mint-public-api-key.ts, prefixed "upk_". Send it as `Authorization: Bearer upk_...`. An invalid, missing, or revoked key gets a uniform 401 (`public-api-invalid-key`) — existence vs. revocation is never distinguishable in the response.'