Adgentek Publisher API

openapi: 3.2.0
info:
  title: Adgentek Publisher 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: publisher
  description: Publisher-facing endpoints (publisher API keys).
paths:
  /v1/publisher/reporting/overview:
    get:
      tags:
      - publisher
      summary: Aggregated revenue overview
      description: 'Revenue from the `publisher_daily_revenue` matview (built over `monetized_events`), keyed by `publisher_id` + day. Requires a publisher key carrying the `pub:reports:read` scope. Money fields are summed; rate metrics are recomputed from the summed base.

        NOTE (prototype): the canonical revenue data is keyed by `publisher_id` while the key scopes by `org_id`, and the schema has no sanctioned bridge between them. Org scoping uses an assumption — an org''s publishers are those whose `publishers.user_id` is a member of the org via `org_users`. See `docs/PUBLISHER_REPORTING_FINDINGS.md`.'
      security:
      - PublisherApiKey: []
      parameters:
      - $ref: '#/components/parameters/DateFrom'
      - $ref: '#/components/parameters/DateTo'
      - name: breakdown
        in: query
        description: Row granularity.
        schema:
          type: string
          enum:
          - day
          - publisher
          default: day
      - $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/PublisherReportingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      operationId: getV1PublisherReportingOverview
      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:
    PublisherReportingResponse:
      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