Agentic Keychain Evaluate API

openapi: 3.2.0
info:
  description: 'Agentic Keychain: Autonomous Trading Agents, Signed Results. This API is its skill registry (Agent Skill ROI Registry & Benchmarking); Keychain Trading''s results are read-only static files at https://agentickeychain.com/trading/results.json. This is a commercial registry. It sells some of the skills listed here, through Polar as merchant of record, and its operator earns money when one is bought. The evaluate answer can be "do not buy": it says so when the measured evidence does not cover your task, when the price is not recovered, or when a free alternative is enough. Every purchase ends in a checkout that a human completes. The same operations are MCP tools at /mcp. Fields this API version does not define can appear and have no meaning for a client that does not know them. A kind, delivery or pricing.model value that a client does not know means the capability is not supported by that client; it is never purchasable by inference.'
  title: Agentic Keychain Evaluate API
  version: 0.2.0
servers:
- url: https://agentickeychain.com
tags:
- name: Evaluate
paths:
  /v1/evaluate:
    post:
      description: 'Decide whether a registry capability is worth using or buying for your task, from registry-run benchmarks only. Use when: you have a task and want a recommend, do_not_recommend or undetermined answer with the arithmetic; name a capability to weigh only that one, or leave it out and the registry weighs its closest matches. Not for: one short answer without the arithmetic (resolve_task), a plain list of matches (search_capabilities), two to five named candidates side by side (compare_capabilities), or the break-even figures of one capability without a task (estimate_roi). Input: a plain task description; give model, expected_runs and baseline_cost_estimate_usd for a money estimate, and context for the conditions the capability declares. Output: ak.evaluation.v1 with decision, reasons, expected effect, price, confidence, operator_message, evaluation_id, next steps and an ak.offer.v1 offer (status, next_action, economics, the four evidence kinds listed apart). do_not_recommend is a normal answer.'
      operationId: evaluate_capability
      requestBody:
        content:
          application/json:
            schema:
              properties:
                baseline_cost_estimate_usd:
                  description: What one run of this task costs you today without the capability, in USD.
                  exclusiveMinimum: 0
                  type: number
                budget_policy:
                  description: Your operator's spending policy; the answer says whether a purchase fits it. Every purchase still needs human approval.
                  properties:
                    absolute_purchase_limit_usd:
                      description: The highest price in USD for one purchase; a price above it is outside the policy.
                      type: number
                    auto_purchase:
                      description: 'When your operator allows a purchase without asking first: enabled (true or false), max_price_usd, and minimum_expected_roi (expected net saving divided by the price). The answer says whether the policy would allow it; these tools never charge.'
                      type: object
                    human_approval_required:
                      description: 'above_usd: a price above this amount in USD needs your operator''s approval even where auto_purchase is enabled.'
                      type: object
                    monthly_budget_usd:
                      description: Your operator's budget for this month in USD.
                      type: number
                    spent_this_month_usd:
                      description: What is already spent of that budget this month in USD (0 when left out).
                      type: number
                  type: object
                capability:
                  description: Capability id (ak:publisher:name or ak:publisher:name:x.y.z), ak:// URI or slug.
                  type: string
                constraints:
                  description: Limits you set for the answer; a capability outside them is reported as blocked, with the reason code.
                  properties:
                    max_cost_usd:
                      description: The highest price in USD you accept; a capability priced above it is blocked (over_max_cost).
                      minimum: 0
                      type: number
                    minimum_confidence:
                      description: The lowest confidence in the measured saving you accept, from 0.5 to 0.999 (default 0.9); below it the answer is blocked (below_minimum_confidence).
                      maximum: 0.999
                      minimum: 0.5
                      type: number
                  type: object
                context:
                  additionalProperties:
                    type:
                    - string
                    - number
                    - integer
                    - boolean
                  description: Facts about your situation, keyed by the capability's parameter names (e.g. log_lines).
                  type: object
                expected_runs:
                  description: How many times you expect to perform this kind of task.
                  minimum: 1
                  type: integer
                model:
                  description: The model you run on, e.g. claude-sonnet-5. Savings are reported only for measured models.
                  type: string
                task:
                  description: Plain description of the task you are about to do (at most 4000 characters).
                  type: string
              required:
              - task
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error (ak.error.v1)
      summary: Should I use a capability for this task?
      tags:
      - Evaluate
components:
  schemas:
    Error:
      properties:
        error:
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
          - code
          - message
          - retryable
          type: object
        schema:
          const: ak.error.v1
      required:
      - schema
      - error
      type: object