Adgentek Advertiser API

openapi: 3.2.0
info:
  title: Adgentek Advertiser API
  version: 0.1.0
  description: 'Standalone Ruby (Sinatra) API for the Adgentek platform, talking directly to the Supabase Postgres database. Two audiences authenticate with their own kind of API key and each sees only its own data:


    * **Advertisers** — `advertiser_api_keys`, capability = `permissions` flag.

    * **Publishers** — `publisher_api_keys`, capability = `scope` entry.


    Both send their key in the `x-api-key` header. Each endpoint accepts exactly one audience, so a key of the wrong type simply fails the lookup. The key''s `org_id` scopes every result.

    **Super admin.** A third audience — platform super admins — authenticates with a service token (`adg_admin_` prefix) in the `x-admin-token` header, resolved against `admin_service_tokens`. Super-admin endpoints live under `/v1/admin/...` and are NOT org-scoped: they aggregate across every org by default, with an optional `org_id` query param to focus a single org.

    ## Versioning The API contract version is carried in the URL path (`/v1/...`) and echoed on every response in the `X-API-Version` header. The deployed build''s release version is in `X-Service-Version` (and at `GET /version`). Breaking changes ship under a new path prefix (`/v2/...`); additive changes stay within the current version.'
servers:
- url: http://localhost:4567
  description: Local development
- url: https://api.adgentek.ai
  description: Production (adjust to your deployed host)
tags:
- name: Advertiser
  description: Advertiser-facing endpoints (advertiser API keys).
paths:
  /v1/advertiser/reporting/campaigns:
    get:
      tags:
      - Advertiser
      summary: Aggregated campaign reporting
      description: Campaign performance from `advertiser_daily_rollup`, scoped to the caller's org. Requires an advertiser key carrying the `reporting` permission. Rate KPIs are recomputed from the summed base metrics.
      security:
      - AdvertiserApiKey: []
      parameters:
      - $ref: '#/components/parameters/DateFrom'
      - $ref: '#/components/parameters/DateTo'
      - name: breakdown
        in: query
        description: Row granularity.
        schema:
          type: string
          enum:
          - campaign
          - daily
          default: campaign
      - name: campaign_ids
        in: query
        description: Comma-separated campaign UUIDs to filter to. Invalid UUIDs are dropped.
        schema:
          type: string
        example: 11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Aggregated rows, pagination, and the echoed query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertiserReportingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getV1AdvertiserReportingCampaigns
      x-operation-id-source: derived
components:
  responses:
    BadRequest:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Unauthorized:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Forbidden:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    InternalError:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  parameters:
    Offset:
      name: Offset
      in: query
      required: false
      schema:
        type: string
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    DateFrom:
      name: DateFrom
      in: query
      required: false
      schema:
        type: string
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Limit:
      name: Limit
      in: query
      required: false
      schema:
        type: string
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    DateTo:
      name: DateTo
      in: query
      required: false
      schema:
        type: string
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  schemas:
    AdvertiserReportingResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true