upspring-ai Docs API

openapi: 3.2.0
info:
  title: Upspring Public Docs 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: Docs
paths:
  /v1/docs:
    get:
      tags:
      - Docs
      summary: Human/agent-readable API reference (markdown)
      description: 'The full endpoint-by-endpoint reference as `text/markdown` — every param, filter, response field, agent recipe, and error code. Built for LLM/agent consumers: fetch once and keep it in context. Same auth as every other route.'
      responses:
        '200':
          description: The reference document.
          content:
            text/markdown:
              schema:
                type: string
        '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: getV1Docs
      x-operation-id-source: derived
  /v1/docs/ui:
    get:
      tags:
      - Docs
      summary: Visual API reference (browser)
      description: Interactive three-panel reference rendered from this OpenAPI document (Scalar), with a try-it console — paste your API key there to fire real requests. The page itself is the ONE unauthenticated route (a browser navigation can't send a Bearer header); it contains only this spec, and every actual API call still requires a key.
      responses:
        '200':
          description: The reference page.
          content:
            text/html:
              schema:
                type: string
      operationId: getV1DocsUi
      x-operation-id-source: derived
  /v1/openapi.json:
    get:
      tags:
      - Docs
      summary: This OpenAPI document
      description: The machine-readable contract — import into Postman or generate a client from it.
      responses:
        '200':
          description: OpenAPI 3.0 document.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '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: getV1OpenapiJson
      x-operation-id-source: derived
components:
  schemas:
    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.'
  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.'