cloudforbots-com Run API

openapi: 3.2.0
info:
  title: Cloudforbots Com Run API
  version: 1.0.0
  description: 'Operations tagged Run across 2 of this provider''s published API definitions: approve-cloudforbots-com-openapi.json, budget-cloudforbots-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://approve.cloudforbots.com
- url: https://budget.cloudforbots.com
tags:
- name: Run
paths:
  /api/run/check_action:
    post:
      operationId: check_action
      summary: Before a consequential action, ask whether the user's rules auto-approve it
      description: 'Before a consequential action, ask whether the user''s rules auto-approve it. Returns auto_approve, needs_approval (with a plain-English approval card and a link the user can tap) or deny. Free plan is watch-only: it reports what it WOULD decide and logs it for the weekly report, but nothing counts as approved, so ask your user as you normally would.'
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: object
                  description: The action your agent wants to take.
                  properties:
                    type:
                      type: string
                      description: 'Short verb: read, search, draft, send_email, send_message, post, purchase, payment, delete, deploy, change_settings, ...'
                    summary:
                      type: string
                      description: One plain sentence of what will happen, e.g. "Buy a $3.99 domain renewal for example.com".
                    amount_usd:
                      type: number
                      description: Money involved, if any.
                    target:
                      type: string
                      description: 'Who or what it touches: a recipient email, domain, file, repo.'
                    reversible:
                      type: boolean
                      description: Can it be undone easily?
                  required:
                  - type
                  - summary
              required:
              - action
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://approve.cloudforbots.com
  /api/run/get_decision:
    post:
      operationId: get_decision
      summary: Check whether the user approved or rejected an approval card (by card_id and…
      description: Check whether the user approved or rejected an approval card (by card_id and card_token). Only act when status is approved.
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                card_id:
                  type: string
                card_token:
                  type: string
              required:
              - card_id
              - card_token
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://approve.cloudforbots.com
  /api/run/set_rules:
    post:
      operationId: set_rules
      summary: Save the user's rules (needs an API key so they stay yours)
      description: 'Save the user''s rules (needs an API key so they stay yours). Each rule: {name, when:{type:[...], max_usd, min_usd, reversible, target_ends_with:[...]}, verdict:"auto"|"ask"|"deny"}. First matching rule wins; anything unmatched needs approval. Call once without confirm to preview, then with confirm=true.'
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rules:
                  type: array
                  items:
                    type: object
                confirm:
                  type: boolean
              required:
              - rules
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://approve.cloudforbots.com
  /api/run/get_rules:
    post:
      operationId: get_rules
      summary: Show the rules in effect for your key (or the default starter rules)
      description: Show the rules in effect for your key (or the default starter rules).
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://approve.cloudforbots.com
  /api/run/weekly_report:
    post:
      operationId: weekly_report
      summary: 'Draft a plain-English report of the last 7 days: actions checked, how many your…'
      description: 'Draft a plain-English report of the last 7 days: actions checked, how many your rules would auto-approve, how many needed you, top kinds of asks, and rule suggestions. Read-only; sends nothing.'
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://approve.cloudforbots.com
  /api/run/open_budget:
    post:
      operationId: open_budget
      summary: 'Open a hard budget for one agent run before it starts: max dollars, tokens…'
      description: 'Open a hard budget for one agent run before it starts: max dollars, tokens, calls and/or wall-clock seconds. Returns a handle. Give the handle to every sub-agent; they all draw from the same ledger, so one runaway loop or fork cannot exceed the run cap.'
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: What this run is for, e.g. "nightly code cleanup".
                max_usd:
                  type: number
                  description: Dollar cap for the whole run (your own estimates per call).
                max_tokens:
                  type: integer
                  description: Token cap (input + output) for the whole run.
                max_calls:
                  type: integer
                  description: Cap on model/tool calls for the whole run.
                max_seconds:
                  type: integer
                  description: Wall-clock cap in seconds from now.
                ttl_hours:
                  type: integer
                  description: Handle lifetime (free max 24, Pro max 168). Default 24.
                mode:
                  type: string
                  enum:
                  - shadow
                  - enforce
                  description: 'shadow = watch only: track spend and flag where the cap WOULD have stopped the run, never block (free). enforce = return allowed=false at the cap (Pro). Default: enforce on Pro, shadow on free.'
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://budget.cloudforbots.com
  /api/run/reserve:
    post:
      operationId: reserve
      summary: Call BEFORE each model call, tool call or sub-agent spawn with your estimate
      description: Call BEFORE each model call, tool call or sub-agent spawn with your estimate. Returns allowed=true and deducts it, or allowed=false with the limit that tripped. When allowed is false, stop, do not retry, and return your partial result to the user. Atomic, so parallel sub-agents cannot both slip under the cap.
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  description: The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget.
                usd:
                  type: number
                  description: Estimated cost of the next call in USD.
                tokens:
                  type: integer
                  description: Estimated tokens of the next call.
                calls:
                  type: integer
                  description: Number of calls to reserve (default 1).
                note:
                  type: string
                  description: 'Short note, e.g. "web_search #12".'
              required:
              - handle
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://budget.cloudforbots.com
  /api/run/record:
    post:
      operationId: record
      summary: After a call, report the actual usage minus what you reserved (positive if it…
      description: After a call, report the actual usage minus what you reserved (positive if it cost more, negative to give back an overestimate). Keeps the ledger honest without blocking.
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  description: The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget.
                usd:
                  type: number
                tokens:
                  type: integer
                note:
                  type: string
              required:
              - handle
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://budget.cloudforbots.com
  /api/run/budget_status:
    post:
      operationId: budget_status
      summary: See spend vs limits, remaining budget, whether the run is stopped and why, and…
      description: See spend vs limits, remaining budget, whether the run is stopped and why, and the last 20 ledger events. Set close=true when the run finishes.
      security:
      - {}
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  description: The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget.
                close:
                  type: boolean
              required:
              - handle
      responses:
        '200':
          description: Result with job, understood, outcome, usage
          content:
            application/json:
              schema:
                type: object
        '401':
          description: bad_agent_key
        '429':
          description: free_limit_reached (includes upgrade link)
      tags:
      - Run
    servers:
    - url: https://budget.cloudforbots.com
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
x-refined-from:
- approve-cloudforbots-com-openapi.json
- budget-cloudforbots-com-openapi.json