Spindl Ads API

openapi: 3.1.0
info:
  title: Spindl Ads (Embed) API
  version: v1
  description: >-
    Spindl's publisher-facing Ads API serves onchain ad recommendations into a
    publisher's website or mobile app and records impression/click events back
    to Spindl. Publishers fetch recommendation units for a wallet address at a
    named placement, render them, and post impression/click tracking events. A
    hosted iFrame variant renders the same unit server-side. This OpenAPI
    description was generated by the API Evangelist enrichment pipeline from
    Spindl's published Ads documentation at
    https://docs.spindl.xyz/ads/start-here; paths, headers, parameters and the
    response shape are transcribed verbatim from that page.
  contact:
    name: Spindl
    email: contact@spindl.xyz
    url: https://docs.spindl.xyz/ads/start-here
  license:
    name: Proprietary
servers:
- url: https://e.spindlembed.com/v1
  description: >-
    Spindl ad embed / serving host. Separate registrable domain from
    spindl.xyz, documented as the Ads base by Spindl's own docs
    (docs.spindl.xyz/ads/start-here) and used by Spindl's own npm package
    @spindl-xyz/embed-react; the live 401 on this host sets a __cf_bm cookie
    scoped to Domain=spindlembed.com (and a Coinbase cb_dm cookie, consistent
    with the January 2025 Coinbase/Base acquisition).
security:
- PublisherApiKey: []
tags:
- name: Ads
  description: Fetch onchain ad recommendations and record impressions/clicks.
paths:
  /render/{publisher_id}:
    get:
      operationId: fetchRecommendations
      summary: Fetch ad recommendations for a wallet at a placement
      description: >-
        Returns ranked ad recommendation units for the given publisher,
        placement and wallet address. Each item carries an `impressionId` that
        must be posted back via `trackAdEvent` when the unit is shown.
      tags:
      - Ads
      security:
      - PublisherApiKey: []
      parameters:
      - name: publisher_id
        in: path
        required: true
        description: Publisher identifier, provided by the Spindl team.
        schema:
          type: string
      - name: placement_id
        in: query
        required: true
        description: Placement identifier, from the Placements tab in the Spindl app.
        schema:
          type: string
      - name: address
        in: query
        required: true
        description: The wallet address, in the form of 0x…
        schema:
          type: string
      - name: limit
        in: query
        required: true
        description: The number of recommendations to return (usually 1).
        schema:
          type: integer
      - name: country
        in: query
        required: true
        description: >-
          Two-letter country code for the country the request originated from.
          Cloudflare users can pass CF-IPCountry directly.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: chain_id
        in: query
        required: false
        description: Numerical chain ID where this unit is being rendered.
        schema:
          type: integer
      responses:
        '200':
          description: Ranked recommendation units.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationList'
        '401':
          description: Missing or invalid publisher API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route or publisher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /external/track:
    post:
      operationId: trackAdEvent
      summary: Post an impression or click
      description: >-
        Record an ad event. Called every time a recommendation is shown on
        screen (impression) and when it is clicked.
      tags:
      - Ads
      security:
      - PublisherApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdEvent'
            example:
              type: impression
              impression_id: 4b0a2d0e-0000-0000-0000-000000000000
      responses:
        '200':
          description: Event recorded.
        '401':
          description: Missing or invalid publisher API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /serve:
    get:
      operationId: serveAdIframe
      summary: Hosted iFrame ad unit
      description: >-
        Returns a renderable HTML ad unit for direct embedding in an iframe.
        Documented as an unauthenticated iframe `src`; the publisher and
        placement are identified by query parameters.
      tags:
      - Ads
      security: []
      parameters:
      - name: publisher_id
        in: query
        required: true
        schema:
          type: string
      - name: placement_id
        in: query
        required: true
        schema:
          type: string
      - name: address
        in: query
        required: false
        description: Wallet address to target the unit with.
        schema:
          type: string
      responses:
        '200':
          description: HTML ad unit.
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    RecommendationList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
    Recommendation:
      type: object
      properties:
        id:
          type: string
        impressionId:
          type: string
          description: Echo this back on trackAdEvent when the unit is shown or clicked.
        type:
          type: string
          description: Format of the unit.
          examples:
          - card
          - iframe
          - discord
        title:
          type: string
        context:
          type: object
          description: Reason the unit was returned (social context, onchain activity).
          properties:
            text:
              type: string
        description:
          type: string
        imageUrl:
          type: string
          format: uri
        imageAltText:
          type: string
        ctas:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              href:
                type: string
                format: uri
    AdEvent:
      type: object
      required:
      - type
      - impression_id
      properties:
        type:
          type: string
          description: Event type.
          enum:
          - impression
          - click
        impression_id:
          type: string
          description: The impressionId returned by fetchRecommendations.
    Error:
      type: object
      description: >-
        grpc-gateway / Google API error model observed live on this host
        (numeric `code`, `message`, `details[]`) — NOT the {statusCode,message}
        envelope used by the Server-to-Server API on api.spindl.xyz.
      properties:
        code:
          type: integer
          description: gRPC status code (16 = UNAUTHENTICATED, 5 = NOT_FOUND).
          example: 16
        message:
          type: string
          example: API key is required
        details:
          type: array
          items:
            type: object
  securitySchemes:
    PublisherApiKey:
      type: apiKey
      in: header
      name: X-API-ACCESS-KEY
      description: >-
        Publisher API Token generated on the Settings screen in the Spindl app.
        Distinct from the Server-to-Server X-API-Key and from the client-side
        SDK key. Must be treated as a secret and never shipped in public-facing
        code.
x-generated: '2026-08-13'
x-method: generated
x-source: https://docs.spindl.xyz/ads/start-here