openapi: 3.2.0
info:
  title: Kann KI das? Agent API
  version: 1.1.0
  description: Faceted product search plus machine-readable availability and buyer-confirmed Stripe Checkout for fixed sponsor placements.
servers:
- url: https://kannkidas.de/api
tags:
- name: Agent
paths:
  /agent/register:
    post:
      operationId: registerAgentClient
      summary: Register an OAuth client for an agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
      responses:
        '201':
          description: Client credentials returned once
        '400':
          description: Invalid registration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Agent
  /agent/purchases:
    post:
      operationId: createSponsorPurchase
      summary: Create an idempotent Stripe Checkout Session
      description: Call only after the buyer explicitly confirms a live slot, price and term. Payment details are collected by Stripe.
      security:
      - oauth2:
        - sponsorship:write
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
      x-payment-info:
        intent: session
        method: stripe
        amount: 99000
        currency: EUR
        methods:
        - method: stripe
          type: hosted_checkout
      responses:
        '201':
          description: Checkout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
        '401':
          description: Bearer token missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Slot unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Agent
  /agent/purchases/{purchase_id}:
    get:
      operationId: getSponsorPurchase
      summary: Read a purchase without exposing buyer PII
      security:
      - oauth2:
        - sponsorship:read
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Purchase state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
        '404':
          description: Unknown purchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Agent
components:
  schemas:
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    Purchase:
      type: object
      required:
      - purchase_id
      - slot_id
      - status
      - status_url
      properties:
        purchase_id:
          type: string
        slot_id:
          type: string
        status:
          enum:
          - checkout_created
          - paid
          - expired
        checkout_url:
          type: string
          format: uri
        status_url:
          type: string
          format: uri
        expires_at:
          type: string
          format: date-time
        amount:
          type: integer
          const: 99000
        currency:
          type: string
          const: EUR
    RegistrationRequest:
      type: object
      additionalProperties: false
      required:
      - name
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 80
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            enum:
            - sponsorship:read
            - sponsorship:write
          default:
          - sponsorship:read
    PurchaseRequest:
      $ref: https://kannkidas.de/schema/agent-purchase.json
  securitySchemes:
    clientBasic:
      type: http
      scheme: basic
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://kannkidas.de/api/oauth/token
          scopes:
            sponsorship:read: Read own purchase status
            sponsorship:write: Create a confirmed checkout