BillboardBug Blob API

openapi: 3.2.0
info:
  title: BillboardBug Public Blob 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: Blob
paths:
  /blobs:
    head:
      tags:
      - Blob
      summary: Check whether a blob exists
      parameters:
      - name: id
        in: query
        description: The blob ID returned from a previous upload (e.g. `abc123.jpg`).
        style: form
        schema:
          type: string
      - name: category
        in: query
        description: 'Storage category. One of: `billboard-image`, `billboard-video`, `storefront-image`, `post-image`, `post-video`, `profile-picture`, `profile-banner`.'
        style: form
        schema:
          type: string
      responses:
        '200':
          description: Blob exists.
        '404':
          description: Blob not found.
      operationId: headBlobs
      x-operation-id-source: derived
    get:
      tags:
      - Blob
      summary: Download a blob (image or video)
      description: 'Returns the raw file with the correct `Content-Type` header. Supports HTTP range requests for partial content (video streaming).


        Use the `id` returned from the upload endpoint as-is. The `category` must match the one used at upload time.'
      parameters:
      - name: id
        in: query
        description: The blob ID returned from a previous upload.
        style: form
        schema:
          type: string
      - name: category
        in: query
        description: 'Storage category. One of: `billboard-image`, `billboard-video`, `storefront-image`, `post-image`, `post-video`, `profile-picture`, `profile-banner`.'
        style: form
        schema:
          type: string
      responses:
        '200':
          description: Full file stream.
        '206':
          description: Partial file stream (range request).
        '404':
          description: Blob not found.
      operationId: getBlobs
      x-operation-id-source: derived
    post:
      tags:
      - Blob
      summary: Upload a file (image or video)
      description: 'Upload a file as `multipart/form-data`. On success the response contains an `id` string.


        Only JPEG images (max 100 MB) and MP4 videos (max 2 GB) are accepted. The file''s `Content-Type` must match its actual contents.


        **Workflow:**

        1. Upload the file here → receive `{ "id": "..." }`

        2. Pass that `id` as the `imageId` or `videoId` field when calling

        `POST /business/quick-create-deal` or `PUT /business/quick-update-deal/{storefrontId}/{billboardId}`


        **Category values:**


        | Value | Use for | Recommended size |

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

        | `billboard-image` | Deal/billboard image (`imageId`) | 640 × 373 px |

        | `billboard-video` | Deal/billboard video (`videoId`) | 640 × 373 px |

        | `storefront-image` | Storefront (business) profile image | — |

        | `post-image` | Post image | — |

        | `post-video` | Post video | — |

        | `profile-picture` | Account profile photo | — |

        | `profile-banner` | Account cover/banner photo | — |'
      parameters:
      - name: category
        in: query
        description: Storage category (see table above).
        style: form
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The file to upload (multipart/form-data).
                  format: binary
            encoding:
              file:
                style: form
      responses:
        '200':
          description: 'Returns `{ "id": "<blob-id>" }` — store this and use it as the `imageId` or `videoId` on deals.'
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: string
            text/json:
              schema:
                type: string
        '400':
          description: No file provided or file is empty.
      operationId: postBlobs
      x-operation-id-source: derived
    delete:
      tags:
      - Blob
      summary: Delete a blob
      parameters:
      - name: id
        in: query
        description: The blob ID to delete.
        style: form
        schema:
          type: string
      - name: category
        in: query
        description: 'Storage category the blob belongs to. One of: `billboard-image`, `billboard-video`, `storefront-image`, `post-image`, `post-video`, `profile-picture`, `profile-banner`.'
        style: form
        schema:
          type: string
      responses:
        '200':
          description: Blob deleted successfully.
      operationId: deleteBlobs
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-Api-Key
      in: header