openapi: 3.1.0
info:
  title: PostOmnia AI Capability API
  version: 0.3.0
  description: >-
    Complete, deny-by-default PostOmnia capability API for ChatGPT Actions and
    other AI clients. First call listPostOmniaCapabilities, then invoke a fixed
    capability ID. The caller cannot provide an HTTP method, path, base URL,
    user ID, role, or workspace ID. Costly and consequential operations require
    an idempotency key. Posting (create, publish, schedule, retry, recycle,
    evergreen, autopilot run) executes immediately with an idempotency key and no
    approval. Deletion, billing, e-mail delivery, and public link creation still
    require an exact approval in the signed-in PostOmnia dashboard. Completed or
    failed idempotency records are retained for 30 days by default; active runs
    are never evicted because of age.
servers:
  - url: 'https://postomnia.de/api'
    description: PostOmnia API
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: PostOmnia API key. Never include it in prompts or capability input.
  parameters:
    TeamId:
      name: x-team-id
      in: header
      required: false
      description: Explicit workspace ID for users who belong to more than one workspace.
      schema:
        type: string
  schemas:
    Capability:
      type: object
      required: [id, category, description, availability, effect, allowed, input]
      properties:
        id: { type: string, examples: [posts.create] }
        version: { type: integer }
        category: { type: string }
        description: { type: string }
        availability:
          type: string
          enum: [available, human_required, transport_only]
        effect:
          type: string
          enum: [read, write, costly, external, destructive, financial]
        requiresHumanApproval: { type: boolean }
        conditionalHumanApproval: { type: boolean }
        requiresIdempotencyKey: { type: boolean }
        conditionalIdempotencyKey: { type: boolean }
        allowed: { type: boolean }
        roles:
          type: array
          items: { type: string }
        input:
          type: object
          properties:
            fields:
              type: array
              items: { type: string }
            required:
              type: array
              items: { type: string }
            allowsAdditionalFields: { type: boolean }
            maxBytes: { type: integer }
        reason: { type: string }
        dashboardPath: { type: string }
    InvokeRequest:
      type: object
      additionalProperties: false
      required: [operation]
      properties:
        operation:
          type: string
          description: Exact capability ID returned by listPostOmniaCapabilities.
          examples: [posts.create]
        input:
          type: object
          description: Capability-specific JSON input. Use only fields listed by the catalog.
          additionalProperties: true
          default: {}
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 160
          pattern: '^[A-Za-z0-9._:-]+$'
          description: Stable unique key required for costly and consequential operations. Reuse it for retries of the exact same request; completed and failed keys are retained for 30 days by default.
        approvalId:
          type: string
          description: Approval ID returned by a previous confirmation_required response after the signed-in user approved it.
    InvokeResponse:
      oneOf:
        - type: object
          required: [status, operation, result]
          properties:
            status: { type: string, const: completed }
            operation: { type: string }
            cached: { type: boolean }
            result: {}
        - type: object
          required: [status, operation, approvalId, summary, expiresAt]
          properties:
            status: { type: string, const: confirmation_required }
            operation: { type: string }
            approvalId: { type: string }
            summary: { type: string }
            expiresAt: { type: string, format: date-time }
            actionUrl: { type: string, format: uri }
            next: { type: string }
    Error:
      type: object
      required: [error]
      properties:
        error: { type: string }
        error_code: { type: string }
        details: { type: object, additionalProperties: true }
paths:
  /automation/capabilities:
    get:
      operationId: listPostOmniaCapabilities
      summary: Discover every classified PostOmnia product capability.
      description: >-
        Returns callable operations, human-only handoffs, transport-only
        equivalents, required roles, input fields, effect classes, and coverage.
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - name: category
          in: query
          required: false
          schema: { type: string }
        - name: effect
          in: query
          required: false
          schema: { type: string }
        - name: availability
          in: query
          required: false
          schema:
            type: string
            enum: [available, human_required, transport_only]
        - name: query
          in: query
          required: false
          schema: { type: string }
      responses:
        '200':
          description: Capability catalog and coverage counts.
          content:
            application/json:
              schema:
                type: object
                required: [capabilities, coverage]
                properties:
                  capabilities:
                    type: array
                    items: { $ref: '#/components/schemas/Capability' }
                  coverage:
                    type: object
                    additionalProperties: { type: integer }
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /automation/invoke:
    post:
      operationId: invokePostOmniaCapability
      summary: Invoke one fixed PostOmnia capability.
      description: >-
        Executes through the shared capability dispatcher with current
        membership, workspace isolation, role checks, input limits, secret
        redaction, audit events, idempotency, rate limits, and dashboard approval
        for consequential actions. Never invent an operation ID or input field.
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InvokeRequest' }
      responses:
        '200':
          description: Completed result or a confirmation request.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InvokeResponse' }
        '400':
          description: Invalid capability input.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '403':
          description: Role, human-only, or approval denial.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '409':
          description: Idempotency or approval conflict.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429':
          description: Per-user and per-workspace automation rate limit.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
