BillboardBug Global Config API

openapi: 3.2.0
info:
  title: BillboardBug Public Global Config 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: GlobalConfig
paths:
  /global-config/all:
    get:
      tags:
      - GlobalConfig
      summary: Get global config
      description: Returns platform-wide configuration including advertising costs. `BillboardDayAdCost` is the per-day featured cost stored as cents × 100 (e.g. 500 = $0.05).
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GlobalConfigResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalConfigResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/GlobalConfigResponse'
      operationId: getGlobalConfigAll
      x-operation-id-source: derived
components:
  schemas:
    AiProviderResponse:
      type: object
      properties:
        type:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        supportsImage:
          type: boolean
        supportsText:
          type: boolean
      additionalProperties: false
    GlobalConfigResponse:
      type: object
      properties:
        billboardDayAdCost:
          type: integer
          format: int32
        billingDayStart:
          type:
          - string
          - 'null'
        billingDayEnd:
          type:
          - string
          - 'null'
        affiliateCommissionPercentage:
          type: integer
          format: int32
        minPayout:
          type: integer
          format: int32
        maxPayout:
          type: integer
          format: int32
        oneMonthDayAdCost:
          type: integer
          format: int32
        threeMonthDayAdCost:
          type: integer
          format: int32
        sixMonthDayAdCost:
          type: integer
          format: int32
        twelveMonthDayAdCost:
          type: integer
          format: int32
        aiProviders:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AiProviderResponse'
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-Api-Key
      in: header