openapi: 3.2.0
info:
  title: sipi.bot — Spend Firewall for AI Agents Evaluate 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: Evaluate
  description: The core spend-decision call an agent makes
paths:
  /v1/transactions/evaluate:
    post:
      tags:
      - Evaluate
      summary: Evaluate a proposed agent spend
      description: '**The core call.** An autonomous agent calls this *before* it spends money. sipi.bot evaluates the transaction against every active rule and returns APPROVED, BLOCKED, or FLAGGED without a model call.


        Auth is optional in free / self-host mode; pass a Bearer agent API key to attribute the transaction to a registered agent and scope per-agent rules.'
      operationId: evaluateTransaction
      security:
      - {}
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
            examples:
              blocked_unknown_merchant:
                summary: Block an unknown merchant
                value:
                  amount: 6200
                  merchant: unknown-gpu.ru
                  category: compute
              flag_over_threshold:
                summary: Flag a high-value txn for human review
                value:
                  amount: 2200
                  merchant: anthropic.com
                  category: api
              approve_normal:
                summary: Approve a normal spend
                value:
                  amount: 12.5
                  merchant: openai.com
                  category: api
      responses:
        '200':
          description: Decision returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    TransactionRequest:
      type: object
      required:
      - amount
      properties:
        amount:
          type: number
          format: float
          description: Transaction amount in the given currency.
          example: 6200
        merchant:
          type: string
          description: Merchant name or domain the agent wants to pay.
          example: unknown-gpu.ru
        category:
          type: string
          description: Spend category, e.g. compute / api / ads / travel.
          example: compute
        currency:
          type: string
          description: ISO 4217 currency code.
          default: USD
          example: USD
        description:
          type: string
          description: Optional free-text description of the proposed spend.
          example: A100 GPU rental
        timestamp:
          type: string
          format: date-time
          description: Optional ISO-8601 timestamp; defaults to now (UTC).
          example: '2026-07-18T02:14:00Z'
    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.
    EvaluationResponse:
      type: object
      properties:
        decision:
          $ref: '#/components/schemas/Decision'
        reason:
          type: string
          description: Human-readable explanation; the rule label if a rule tripped.
          example: Merchant not on allowlist
        rule_id:
          type:
          - string
          - 'null'
          description: ID of the rule that decided the outcome, if any.
        triggered:
          type: array
          description: Every rule that matched this transaction (in evaluation order).
          items:
            type: object
            properties:
              rule_id:
                type: string
              rule_type:
                type: string
              action:
                $ref: '#/components/schemas/Decision'
              label:
                type: string
        transaction_id:
          type:
          - string
          - 'null'
          description: Audit-log ID for the recorded transaction.
        amount:
          type: number
        merchant:
          type: string
        category:
          type: string
  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