BillboardBug AI API

openapi: 3.2.0
info:
  title: BillboardBug Public AI API
  description: 'The BillboardBug Public API lets you manage your deals, posts, and storefronts programmatically. You can also use the API to generate AI images — useful for creating deal artwork without a design tool. ## Getting Started

    1. **Create an account** at https://app.billboardbug.com if you don''t have one already. 2. Log in and navigate to **Settings → API Keys** to generate a key. 3. Pass the key in the `X-Api-Key` header on every request. All content created or modified through the API is associated with the account that owns the key. If that account is suspended the key will be rejected. ## Creating a Deal


    **Step 0 — (Optional) Generate an image with AI**


    Use the image generation endpoint to create deal artwork from a text prompt — no design tool needed. Grok is recommended for its flexible aspect ratio support. ```

    POST /ai/image

    X-Api-Key:

    X-Version: 1

    Content-Type: application/json

    ```

    ```json

    {

    "prompt": "A bright summer sale banner for a clothing store, bold colors",

    "aiProvider": 5,

    "width": 640,

    "height": 373

    }

    ```


    The response contains a `base64Data` field (`data:image/jpeg;base64,...`) which you can convert

    to a file and upload in Step 1. See **POST /ai/image** for provider options and resolution details. **Step 1 — Upload an image or video**


    Upload an image (recommended 640 × 373 px JPEG) using category `billboard-image`, or a video (640 × 373 px) using category `billboard-video`. Save the `id` from the response and pass it as `imageId` or `videoId` in the deal request. ```

    POST /blobs?category=billboard-image

    X-Api-Key:

    X-Version: 3

    Content-Type: multipart/form-data


    file=

    ```


    Response:

    ```json

    { "id": "abc123.jpg" }

    ```


    **Step 2 — Create the deal**


    Pass the blob `id` as `imageId`. Hours use `HH:MM` (24-hour). Omit `altitudeMeters` for a standard pole mount. ```

    POST /business/quick-create-deal

    X-Api-Key:

    X-Version: 1

    Content-Type: application/json

    ```

    ```json

    {

    "title": "Summer Sale",

    "description": "20% off this weekend.",

    "imageId": "abc123.jpg",

    "name": "My Store",

    "locationDescription": "123 Main St, Springfield, IL",

    "locationLat": 39.7817,

    "locationLng": -89.6501,

    "mondayEnabled": true, "monday24Hours": false,

    "mondayOpen": "09:00", "mondayClose": "17:00",

    "tuesdayEnabled": true, "tuesday24Hours": false,

    "tuesdayOpen": "09:00", "tuesdayClose": "17:00",

    "wednesdayEnabled": true, "wednesday24Hours": false,

    "wednesdayOpen": "09:00", "wednesdayClose": "17:00",

    "thursdayEnabled": true, "thursday24Hours": false,

    "thursdayOpen": "09:00", "thursdayClose": "17:00",

    "fridayEnabled": true, "friday24Hours": false,

    "fridayOpen": "09:00", "fridayClose": "17:00",

    "saturdayEnabled": true, "saturday24Hours": false,

    "saturdayOpen": "09:00", "saturdayClose": "17:00",

    "sundayEnabled": true, "sunday24Hours": false,

    "sundayOpen": "09:00", "sundayClose": "17:00",

    "isEnabled": true

    }

    ```


    The response contains `storefrontId` and `billboardId` — save these to update the deal later. **Featured deals (optional)**


    Setting `isFeatured: true` on a deal promotes it and incurs a daily cost. The per-day rate is returned by

    `GET /global-config/all` as `billboardDayAdCost`, which is the dollar amount × 100 with no cents

    (e.g. `500` = $5.00/day). Discount options are available for purchase under Business → Discounts. Your account must have a billing method on file to set a deal as featured. **Step 3 — Update the deal**


    Use the same body shape as create. ```

    PUT /business/quick-update-deal/{storefrontId}/{billboardId}

    X-Api-Key:

    X-Version: 1

    Content-Type: application/json

    ```


    ## Creating a Post


    Posts are standalone pieces of content (text, image, or video) attached to your account. To comment on an existing post supply `parentPostId`. **Step 1 — (Optional) Upload an image or video**


    Upload an image (recommended width: 640 px, height varies) using category `post-image`, or a video using category `post-video`. Save the `id` and pass it as `imageId` or `videoId` in the post request.'
  version: 1.0.0
security:
- ApiKey: []
tags:
- name: AI
paths:
  /ai/image:
    post:
      tags:
      - AI
      summary: Generate an image from a text prompt
      description: 'Generates one or more images using an AI image model.


        **Supported providers** (via `aiProvider` field):

        | Value | Provider |

        |-------|----------|

        | `1` | OpenAI (GPT Image 2.5 Flare) |

        | `5` | Grok ⭐ Recommended |


        **Grok is recommended** for image generation.


        ### Width & Height


        Both `width` and `height` are optional. Behavior depends on the provider:


        **Grok** — width/height are used to determine the closest supported aspect ratio.

        The exact pixel values are not used directly; the ratio is snapped to the nearest

        value from Grok''s supported set:

        `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `2:1`, `1:2`, `20:9`, `9:20`, `19.5:9`, `9:19.5`.

        Resolution is set to `2k` when either dimension is ≥ 1500px, otherwise `1k`.

        If omitted, Grok auto-selects the best ratio for the prompt.


        **OpenAI (GPT Image 2.5 Flare)** — only three fixed output sizes are supported:

        - Square (or omitted) → 1024×1024

        - Landscape (width > height) → 1536×1024

        - Portrait (height > width) → 1024×1536


        Returns an array of images as base64-encoded JPEG data URLs.


        **Example request:**

        ```json

        {

        "prompt": "A sunset over a mountain range, photorealistic",

        "aiProvider": 5,

        "width": 1280,

        "height": 720

        }

        ```


        **Example response:**

        ```json

        [

        {

        "base64Data": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB...",

        "url": null,

        "aiProvider": 5

        }

        ]

        ```'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiImageRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/AiImageRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AiImageRequest'
      responses:
        '200':
          description: Array of generated images.
      operationId: postAiImage
      x-operation-id-source: derived
components:
  schemas:
    AiProviderType:
      enum:
      - OpenAi
      - GoogleAi
      - ClaudeAi
      - PerplexityAi
      - Grok
      type: string
    AiImageRequest:
      required:
      - prompt
      type: object
      properties:
        prompt:
          maxLength: 2000
          minLength: 1
          type: string
        aiProvider:
          $ref: '#/components/schemas/AiProviderType'
        width:
          maximum: 8192
          minimum: 1
          type:
          - integer
          - 'null'
          format: int32
        height:
          maximum: 8192
          minimum: 1
          type:
          - integer
          - 'null'
          format: int32
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-Api-Key
      in: header