Spindl Ads API

openapi: 3.2.0
info:
  title: Spindl (Embed) Ads 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:
    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
    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
    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.
    RecommendationList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
  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