Adgentek Meta API

openapi: 3.2.0
info:
  title: Adgentek Meta 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: Meta
  description: Service metadata, health, metrics scrape, and this contract.
paths:
  /health:
    get:
      tags:
      - Meta
      summary: Liveness + DB connectivity probe
      description: No auth. Reports service status, running versions, and whether the DB is reachable.
      security: []
      responses:
        '200':
          description: Service is up (check `db` for database connectivity).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
      operationId: getHealth
      x-operation-id-source: derived
  /metrics:
    get:
      tags:
      - Meta
      summary: Prometheus metrics scrape endpoint
      description: No auth. Prometheus text exposition (`text/plain`) for otelcol scrape → SigNoz. Exposes HTTP RED metrics and build metadata. Not part of the public API surface; restrict at the network layer (localhost / collector only).
      security: []
      responses:
        '200':
          description: Prometheus text format metrics.
          content:
            text/plain:
              schema:
                type: string
      operationId: getMetrics
      x-operation-id-source: derived
  /version:
    get:
      tags:
      - Meta
      summary: Service + API version info
      security: []
      responses:
        '200':
          description: Version metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfo'
      operationId: getVersion
      x-operation-id-source: derived
  /openapi.yaml:
    get:
      tags:
      - Meta
      summary: This OpenAPI contract
      security: []
      responses:
        '200':
          description: The OpenAPI 3.1 document.
          content:
            application/yaml:
              schema:
                type: string
      operationId: getOpenapiYaml
      x-operation-id-source: derived
components:
  schemas:
    VersionInfo:
      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
    Health:
      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