openapi: 3.2.0
info:
  title: sipi.bot — Spend Firewall for AI Agents Rules API
  description: 'sipi.bot sits in front of every transaction an autonomous AI agent attempts and evaluates it against your spend rules — per-transaction caps, daily totals, velocity (runaway-loop protection), merchant allow/block, category limits, time windows, and approval thresholds. It returns APPROVED, BLOCKED, or FLAGGED with a deterministic rules check, before a single dollar moves. Every decision is written to a queryable audit log.


    **The core call an agent makes before spending:** `POST /v1/transactions/evaluate`.


    Auth is optional only for the public evaluation sandbox. Pass `Authorization: Bearer ` for an isolated paid or operator-created workspace. Dashboard and control-plane routes require authentication.'
  version: 0.1.0
  contact:
    name: sipi.bot
    url: https://sipi.bot
    email: sales@sipiteno.com
  license:
    name: MIT
    url: https://github.com/kindrat86/sipi-bot/blob/main/LICENSE
  termsOfService: https://sipi.bot/terms
servers:
- url: https://sipi.bot
  description: Production
security:
- BearerAuth: []
tags:
- name: Rules
  description: Create, list, and delete spend-policy rules
paths:
  /api/rules:
    get:
      tags:
      - Rules
      summary: List all spend rules
      operationId: listRules
      responses:
        '200':
          description: Rules list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
    post:
      tags:
      - Rules
      summary: Add a spend rule
      operationId: addRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleCreate'
      responses:
        '200':
          description: Created rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
  /api/rules/{rule_id}:
    delete:
      tags:
      - Rules
      summary: Delete a spend rule
      operationId: deleteRule
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
components:
  schemas:
    Rule:
      type: object
      properties:
        id:
          type: string
          example: r_per_transaction_500
        rule_type:
          type: string
          enum:
          - per_transaction
          - daily_total
          - velocity
          - merchant_block
          - merchant_allow
          - category_limit
          - time_window
          - approval_threshold
          description: The rule check to apply.
        params:
          type: object
          description: Rule-type-specific parameters.
          example:
            max_amount: 500
        action:
          $ref: '#/components/schemas/Decision'
        priority:
          type: integer
          default: 100
          description: Higher priority rules are evaluated first. First BLOCK wins.
        enabled:
          type: boolean
          default: true
        label:
          type: string
          description: Optional human label used as the reason when the rule trips.
        agent_id:
          type:
          - string
          - 'null'
          description: Scope this rule to a specific agent. null = global.
    Decision:
      type: string
      enum:
      - APPROVED
      - BLOCKED
      - FLAGGED
      description: APPROVED = pass all rules. BLOCKED = violates a hard rule, no money moves. FLAGGED = allowed but crosses an approval threshold, routed to the human queue.
    RuleCreate:
      type: object
      required:
      - rule_type
      properties:
        rule_type:
          type: string
          enum:
          - per_transaction
          - daily_total
          - velocity
          - merchant_block
          - merchant_allow
          - category_limit
          - time_window
          - approval_threshold
        params:
          type: object
          description: Rule-type-specific parameters.
          example:
            max_amount: 500
        action:
          $ref: '#/components/schemas/Decision'
          default: BLOCKED
        priority:
          type: integer
          default: 100
        label:
          type: string
          default: ''
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: A checkout-issued or operator-created API key. ADMIN_TOKEN is accepted only for operator control-plane access.
externalDocs:
  description: Agent card (A2A discovery)
  url: https://sipi.bot/.well-known/agent-card.json