API Evangelist enhancements for the Clix External API v1

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Clix External API v1
  version: '2026-09-19'
  description: >-
    Non-destructive overlay on openapi/clix-so-openapi.yml (the provider's grpc-gateway-generated OpenAPI
    3.1.0, fetched verbatim from https://docs.clix.so/api-reference/openapi.json). Adds the human info the
    generator left out — a title, description, contact, terms, licence, documentation links, a tag
    description, and the rate-limit and error-envelope facts from the docs — without changing any path,
    parameter or schema. Apply with an Overlay 1.0.0 processor; never edit the original.
extends: ./openapi/clix-so-openapi.yml
x-generated: '2026-09-19'
x-method: generated
x-source: https://docs.clix.so/api-reference/overview
actions:
- target: $.info
  update:
    title: Clix External API
    version: v1
    summary: Server-to-server API for Clix mobile push — users, devices, events, ad-hoc pushes, Live Activities and campaign triggers.
    description: >-
      The Clix API enables programmatic control of user management, messaging, campaign execution, and event
      tracking through server-to-server communication. Base URL https://api.clix.so; every request carries
      X-Clix-Project-ID and X-Clix-API-Key (use the SECRET key server-side). JSON only; TLS 1.2+; requests
      terminate after 100 seconds; 10 MB maximum body. Generated by the provider from clix/external/v1/clix.proto
      (grpc-gateway), which is why write actions use custom verbs (messages:send, live-activities:start,
      campaigns/{campaign_id}:trigger) and bodies wrap lists.
    termsOfService: https://clix.so/terms
    contact:
      name: Clix support
      email: support@clix.so
      url: https://docs.clix.so/
    license:
      name: Clix Terms of Service
      url: https://clix.so/terms
    x-original-title: clix/external/v1/clix.proto
    x-original-version: version not set
- target: $
  update:
    externalDocs:
      description: Clix API reference
      url: https://docs.clix.so/api-reference/overview
- target: $.servers[0]
  update:
    description: Production. The only published host; also serves the A2A agent card at /.well-known/agent-card.json and the A2A JSON-RPC endpoint at /a2a.
- target: $.tags[?(@.name=='ClixExternalService')]
  update:
    description: All eleven external operations. Management operations (users, messages:send, campaigns:trigger) share a 1,000 requests/second/project token bucket.
    externalDocs: {url: 'https://docs.clix.so/api-reference/overview'}
- target: $.components.securitySchemes.ApiKeyAuth
  update:
    description: >-
      API key for authentication. Two key types: a PUBLIC key for client-side SDKs (safe to expose) and a
      SECRET key (prefix clix_sk_) for server-to-server operations — user management, message sending,
      campaign triggering. Send together with X-Clix-Project-ID.
- target: $.components.securitySchemes.ProjectIdAuth
  update:
    description: Project ID for authentication. Rate limits are tracked per project on this header.
- target: $.paths['/api/v1/messages:send'].post
  update:
    x-rate-limit: {scope: per-project, limit: 1000, window: 1s, headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After]}
    x-idempotency: none — no idempotency key; a retried request delivers twice. The A2A send-push-notification skill accepts X-Clix-Idempotency-Key.
    x-reversibility: none — a sent push cannot be recalled.
- target: $.paths['/api/v1/campaigns/{campaign_id}:trigger'].post
  update:
    x-rate-limit: {scope: per-project, limit: 1000, window: 1s}
    x-reversibility: none — delivery is asynchronous and no cancel-trigger operation exists; trigger_id is for tracking.
    x-limits: {audience_filter_attributes: 3}
- target: $.paths['/api/v1/users/{project_user_id}'].delete
  update:
    x-reversibility: none — "This action is irreversible and will remove the user and all associated data"; returns 200 even if the user does not exist.
- target: $.paths['/api/v1/users'].post
  update:
    x-idempotency: upsert — "If a user with the same project_user_id already exists, this endpoint will update the existing user's properties"
- target: $.paths['/api/v1/health'].get
  update:
    x-observed: 'Anonymous GET https://api.clix.so/api/v1/health returned an empty 404 on 2026-09-19; treat as authenticated or unexposed.'
- target: $.components.responses
  update:
    TooManyRequests:
      description: Rate limit exceeded — token bucket empty.
      headers:
        Retry-After: {schema: {type: integer}, description: Seconds to wait (typically 1).}
        X-RateLimit-Limit: {schema: {type: integer}}
        X-RateLimit-Remaining: {schema: {type: integer}}
        X-RateLimit-Reset: {schema: {type: integer}, description: Unix timestamp (seconds) when the bucket refills.}
      content:
        application/json:
          schema: {type: object, properties: {error: {type: string}}}
          example: {error: Too Many Requests}
    Unauthorized:
      description: Missing or invalid X-Clix-Project-ID / X-Clix-API-Key. Observed live as text/plain "Missing project id".
      content:
        text/plain: {schema: {type: string}, example: Missing project id}