{
  "openapi": "3.1.0",
  "info": {
    "title": "Metrx desk: public routes",
    "version": "1.0.0",
    "description": "The routes an agent or a person can call with no Metrx account. They read the synthetic Northwind demo (badged `synthetic` in every document) or run a pure function on the caller's own input; none reads a customer organization. Each is limited per address; the limit rides in the X-RateLimit-* headers. Errors are RFC 9457 problems whose classes are documented at https://docs.metrxbot.com/desk#errors. The same tools are exposed over MCP at https://metrxbot.com/api/mcp?set=workforce and as the metrx-desk Claude Code plugin.",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://metrxbot.com"
    }
  ],
  "externalDocs": {
    "url": "https://docs.metrxbot.com/desk",
    "description": "The desk: install, skills, errors."
  },
  "paths": {
    "/api/v1/workforce-review": {
      "get": {
        "operationId": "getWorkforceReview",
        "summary": "The workforce review document for the Northwind demo (no key) or your own organization (key).",
        "description": "With `org=demo` (the default) no key is needed and the document is the synthetic Northwind sample, cached for a few minutes. With `org=me` a Metrx API key with the `read` scope is required (`Authorization: Bearer sk_live_...`) and the document covers the caller's organization. Every figure carries a label: measured, owner-declared, advisory, inferred, insufficient data, synthetic, proposal-not-measured.",
        "parameters": [
          {
            "name": "org",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "demo",
                "me"
              ],
              "default": "demo"
            },
            "description": "`demo` (default, no key) or `me` (your organization, key required)."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "description": "Opaque cursor from `page.next_cursor` of the previous response."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "description": "Roster rows per page."
          }
        ],
        "security": [
          {},
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "The review document.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests per minute per address (30)."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current minute."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WorkforceReview"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_params: One or more inputs are invalid; the fields list says which ones and why. See https://docs.metrxbot.com/desk#errors-invalid-params.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "auth_required: This tool needs a Metrx API key. Create one under Settings → Security and set METRX_API_KEY, or run the demo with org: \"demo\". See https://docs.metrxbot.com/desk#errors-auth-required.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: Too many requests from this address. Wait the number of seconds in retry_after_seconds and try again. See https://docs.metrxbot.com/desk#errors-rate-limited.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "limiter_unavailable (the public limiter is down; Retry-After 30) or demo_unavailable (the demo is being rebuilt; Retry-After 300). The `code` member says which. For `org=me`, `review_unavailable` with the build reason in `code`.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contracts/draft": {
      "post": {
        "operationId": "draftJobContract",
        "summary": "Draft a job contract for one agent from a template. Pure; stores nothing.",
        "description": "Returns the draft body, the errors that would block publishing it, the warnings to look at first, and where to publish it (`set_job_contract`, admin scope). Every number in the result is the caller's own input and is labelled `proposal-not-measured`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DraftContractInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The drafted contract.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests per minute per address (30)."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current minute."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "template",
                        "template_label",
                        "draft",
                        "errors",
                        "warnings",
                        "label",
                        "publish"
                      ],
                      "properties": {
                        "template": {
                          "type": "string"
                        },
                        "template_label": {
                          "type": "string"
                        },
                        "draft": {
                          "type": "object",
                          "description": "The contract body to publish (objective, unit of work, acceptance criteria, budget, human baseline)."
                        },
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Each one blocks publishing."
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "label": {
                          "type": "string",
                          "const": "proposal-not-measured"
                        },
                        "publish": {
                          "type": "object",
                          "properties": {
                            "method": {
                              "type": "string",
                              "const": "POST"
                            },
                            "path": {
                              "type": "string"
                            },
                            "scope": {
                              "type": "string",
                              "const": "admin"
                            },
                            "policy_defaults": {
                              "type": "string",
                              "const": "observe_only"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_params: One or more inputs are invalid; the fields list says which ones and why. See https://docs.metrxbot.com/desk#errors-invalid-params.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: Too many requests from this address. Wait the number of seconds in retry_after_seconds and try again. See https://docs.metrxbot.com/desk#errors-rate-limited.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "limiter_unavailable: The public desk is briefly unavailable while its rate limiter is down. Try again in about 30 seconds; a Metrx API key is not affected. See https://docs.metrxbot.com/desk#errors-limiter-unavailable.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vendor-bill/check": {
      "post": {
        "operationId": "checkVendorBill",
        "summary": "Reconcile a per-resolution vendor bill against your own records. Pure; stores nothing.",
        "description": "Each billed unit is classed matched, disputed (reopened in the ledger), unmatched, uncounted (in `rejected_ids`) or outside coverage from `resolved_ids`, `rejected_ids`, the `ledger` and `covered_spans`. While any unit is uncounted or `import_rejected_count` is above zero the total difference is withheld (`withheld: true`, `delta_count` and `delta_usd` null). `period.from` must be before `period.to`. Amounts are measured from the two inputs (`label: measured`); the result is a reconciliation, not a saving.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VendorBillCheckInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The reconciliation.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests per minute per address (30)."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current minute."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "period",
                        "summary",
                        "rows",
                        "dropped_outside_period",
                        "label",
                        "note"
                      ],
                      "properties": {
                        "period": {
                          "type": "object",
                          "properties": {
                            "from": {
                              "type": "string"
                            },
                            "to": {
                              "type": "string"
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "description": "Counts per class (matched, disputed, unmatched, uncounted, outside_coverage) plus import_rejected, withheld, delta_count, their_usd, delta_usd (both null while withheld), disputed_usd, unmatched_usd, outside_coverage_usd.",
                          "additionalProperties": true
                        },
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "dropped_outside_period": {
                          "type": "integer"
                        },
                        "label": {
                          "type": "string",
                          "const": "measured"
                        },
                        "note": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_params: One or more inputs are invalid; the fields list says which ones and why. See https://docs.metrxbot.com/desk#errors-invalid-params.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: Too many requests from this address. Wait the number of seconds in retry_after_seconds and try again. See https://docs.metrxbot.com/desk#errors-rate-limited.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "limiter_unavailable: The public desk is briefly unavailable while its rate limiter is down. Try again in about 30 seconds; a Metrx API key is not affected. See https://docs.metrxbot.com/desk#errors-limiter-unavailable.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cost-per-resolution": {
      "post": {
        "operationId": "costPerResolution",
        "summary": "The two numbers on a per-resolution bill: price per billed resolution and, with total conversations, the billed-resolution share. Pure; stores nothing.",
        "description": "Divides the bill total by the billed resolution count and, when `total_conversations` is given, states what share of conversations the vendor billed as resolved. `vendor_resolved_definition` is echoed back verbatim as the vendor's definition, not verified. Both numbers are the vendor's own count and are labelled `vendor-reported`, never Verified. The result always ends with `next_step`: send one export (the bill lines with ticket ids plus your ticket export for the same period) and Metrx recounts it through `check_vendor_bill`. Negative or non-numeric input is refused with a message per field.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CostPerResolutionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The two numbers.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests per minute per address (30)."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current minute."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "vendor",
                        "currency",
                        "period",
                        "bill_total",
                        "billed_resolutions",
                        "effective_price_per_resolution",
                        "billed_resolution_share_pct",
                        "total_conversations",
                        "vendor_definition",
                        "provenance",
                        "warnings",
                        "next_step"
                      ],
                      "properties": {
                        "vendor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "currency": {
                          "type": "string"
                        },
                        "period": {
                          "type": "object",
                          "properties": {
                            "from": {
                              "type": "string"
                            },
                            "to": {
                              "type": "string"
                            }
                          }
                        },
                        "bill_total": {
                          "type": "number"
                        },
                        "billed_resolutions": {
                          "type": "integer"
                        },
                        "effective_price_per_resolution": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Rounded to the currency minor unit; null when no resolutions were billed."
                        },
                        "billed_resolution_share_pct": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Percent with one decimal; null without a usable conversation total."
                        },
                        "total_conversations": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "vendor_definition": {
                          "type": "object",
                          "properties": {
                            "text": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "status": {
                              "type": "string"
                            }
                          }
                        },
                        "provenance": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string",
                              "const": "vendor-reported"
                            },
                            "verified": {
                              "type": "boolean",
                              "const": false
                            },
                            "statement": {
                              "type": "string"
                            }
                          }
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "next_step": {
                          "type": "object",
                          "description": "Always last: the recount step.",
                          "properties": {
                            "text": {
                              "type": "string"
                            },
                            "tool": {
                              "type": "string",
                              "const": "metrx_check_vendor_bill"
                            },
                            "skill": {
                              "type": "string",
                              "const": "check-vendor-bill"
                            },
                            "send": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_params: One or more inputs are invalid; the fields list says which ones and why. See https://docs.metrxbot.com/desk#errors-invalid-params.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited: Too many requests from this address. Wait the number of seconds in retry_after_seconds and try again. See https://docs.metrxbot.com/desk#errors-rate-limited.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "limiter_unavailable: The public desk is briefly unavailable while its rate limiter is down. Try again in about 30 seconds; a Metrx API key is not affected. See https://docs.metrxbot.com/desk#errors-limiter-unavailable.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Metrx API key (Settings → Security). Only `org=me` needs one."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem body. `type` is the docs anchor for the class, `title` the class, `detail` the user-facing message. `code` and `error` repeat them for clients that read the Metrx ApiError shape.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "https://docs.metrxbot.com/desk#errors-<class-with-dashes>"
          },
          "title": {
            "type": "string",
            "enum": [
              "auth_required",
              "insufficient_scope",
              "rate_limited",
              "limiter_unavailable",
              "demo_unavailable",
              "unknown_agent_key",
              "invalid_params",
              "transport_error",
              "review_unavailable"
            ]
          },
          "status": {
            "type": "integer",
            "enum": [
              400,
              401,
              403,
              404,
              429,
              502,
              503
            ]
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "auth_required",
              "insufficient_scope",
              "rate_limited",
              "limiter_unavailable",
              "demo_unavailable",
              "unknown_agent_key",
              "invalid_params",
              "transport_error",
              "review_unavailable"
            ]
          },
          "error": {
            "type": "string"
          },
          "retry_after_seconds": {
            "type": "integer",
            "description": "Present on rate_limited, demo_unavailable and review_unavailable. Never on limiter_unavailable, which sends only the Retry-After header."
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 5,
            "description": "Close agent keys, on unknown_agent_key."
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Per-field messages, on invalid_params."
          },
          "required_scope": {
            "type": "string",
            "description": "The scope the key lacks, on insufficient_scope."
          }
        }
      },
      "WorkforceReview": {
        "type": "object",
        "properties": {
          "schema_id": {
            "type": "string",
            "const": "metrx.workforce-review.v1"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "synthetic": {
            "type": "boolean"
          },
          "org": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "minLength": 1
              },
              "label": {
                "type": "string",
                "enum": [
                  "demo",
                  "me"
                ]
              }
            },
            "required": [
              "id",
              "name",
              "label"
            ],
            "additionalProperties": false
          },
          "period": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              },
              "days": {
                "type": "integer",
                "exclusiveMinimum": 0
              }
            },
            "required": [
              "from",
              "to",
              "days"
            ],
            "additionalProperties": false
          },
          "totals": {
            "type": "object",
            "properties": {
              "agents": {
                "type": "integer",
                "minimum": 0
              },
              "spend_usd": {
                "type": "number",
                "minimum": 0
              },
              "spend_label": {
                "type": "string",
                "enum": [
                  "measured",
                  "owner-declared",
                  "advisory",
                  "insufficient data",
                  "synthetic",
                  "inferred",
                  "proposal-not-measured"
                ]
              },
              "events": {
                "type": "integer",
                "minimum": 0
              },
              "tasks": {
                "type": "integer",
                "minimum": 0
              },
              "confirmed_outcomes": {
                "type": "integer",
                "minimum": 0
              },
              "cost_per_confirmed_usd": {
                "anyOf": [
                  {
                    "type": "number",
                    "minimum": 0
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "human_baseline_usd": {
                "anyOf": [
                  {
                    "type": "number",
                    "minimum": 0
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "review_corrections": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "no_contract": {
                "type": "object",
                "properties": {
                  "agents": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "spend_usd": {
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "agents",
                  "spend_usd"
                ],
                "additionalProperties": false
              },
              "retired_still_running": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "agents",
              "spend_usd",
              "spend_label",
              "events",
              "tasks",
              "confirmed_outcomes",
              "cost_per_confirmed_usd",
              "human_baseline_usd",
              "review_corrections",
              "no_contract"
            ],
            "additionalProperties": false
          },
          "roster": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "agent_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "agent_key": {
                  "type": "string",
                  "minLength": 1
                },
                "name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "team": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "owner": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "primary_model": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "idle",
                    "error",
                    "archived"
                  ]
                },
                "spend_usd": {
                  "type": "number",
                  "minimum": 0
                },
                "spend_label": {
                  "type": "string",
                  "enum": [
                    "measured",
                    "owner-declared",
                    "advisory",
                    "insufficient data",
                    "synthetic",
                    "inferred",
                    "proposal-not-measured"
                  ]
                },
                "events": {
                  "type": "integer",
                  "minimum": 0
                },
                "tasks": {
                  "type": "integer",
                  "minimum": 0
                },
                "cost_per_confirmed_usd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "minimum": 0
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "confirmed_outcomes": {
                  "type": "integer",
                  "minimum": 0
                },
                "human_baseline_usd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "minimum": 0
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "idle_days": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": 0
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "contract": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "present": {
                          "type": "boolean"
                        },
                        "version": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "owner": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "budget_usd_per_month": {
                          "anyOf": [
                            {
                              "type": "number",
                              "minimum": 0
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "present",
                        "version",
                        "owner",
                        "budget_usd_per_month"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "scorecard": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "empty",
                            "pass",
                            "fail",
                            "insufficient",
                            "tracking"
                          ]
                        },
                        "primary_action": {
                          "type": "string"
                        },
                        "summary": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "window": {
                                  "type": "string"
                                },
                                "events": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "outcomes": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "human_verified": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "error_flagged": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "cost_usd": {
                                  "type": "number",
                                  "minimum": 0
                                }
                              },
                              "required": [
                                "window",
                                "events",
                                "outcomes",
                                "human_verified",
                                "error_flagged",
                                "cost_usd"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "state",
                        "primary_action",
                        "summary"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "retired_still_running": {
                  "type": "boolean"
                }
              },
              "required": [
                "agent_id",
                "agent_key",
                "name",
                "team",
                "owner",
                "primary_model",
                "status",
                "spend_usd",
                "spend_label",
                "events",
                "tasks",
                "cost_per_confirmed_usd",
                "confirmed_outcomes",
                "human_baseline_usd",
                "idle_days",
                "contract",
                "scorecard"
              ],
              "additionalProperties": false
            }
          },
          "candidates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rule": {
                  "type": "string",
                  "enum": [
                    "idle_agent",
                    "no_contract",
                    "model_swap"
                  ]
                },
                "agent_ids": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "minItems": 1
                },
                "agent_keys": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  },
                  "minItems": 1
                },
                "count_label": {
                  "type": "string",
                  "enum": [
                    "measured",
                    "advisory"
                  ]
                },
                "money_usd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "minimum": 0
                    },
                    {
                      "type": "string",
                      "const": "insufficient data"
                    }
                  ]
                },
                "money_label": {
                  "type": "string",
                  "enum": [
                    "measured",
                    "owner-declared",
                    "advisory"
                  ]
                },
                "n": {
                  "type": "number",
                  "minimum": 0
                },
                "threshold": {
                  "type": "number",
                  "minimum": 0
                },
                "evidence_link": {
                  "type": "string",
                  "pattern": "^\\/"
                },
                "proof": {
                  "type": "string",
                  "enum": [
                    "model_swap",
                    "decision"
                  ]
                },
                "queue_kind": {
                  "type": "string",
                  "enum": [
                    "idle_agent",
                    "no_contract",
                    "proposal"
                  ]
                },
                "unlock": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "rule",
                "agent_ids",
                "agent_keys",
                "count_label",
                "money_usd",
                "money_label",
                "n",
                "threshold",
                "evidence_link",
                "proof",
                "queue_kind",
                "unlock"
              ],
              "additionalProperties": false
            }
          },
          "decisions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "agent_key": {
                  "type": "string",
                  "minLength": 1
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "expand",
                    "re_specify",
                    "combine",
                    "retire"
                  ]
                },
                "decided_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "url": {
                  "type": "string",
                  "pattern": "^\\/"
                }
              },
              "required": [
                "id",
                "agent_key",
                "kind",
                "decided_at",
                "url"
              ],
              "additionalProperties": false
            }
          },
          "share": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "xlsx_url": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "as_of": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "hash": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "url",
                  "xlsx_url",
                  "as_of",
                  "hash"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "next_steps": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "ok",
              "no_events",
              "no_outcomes",
              "timeout"
            ]
          },
          "state_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "page": {
            "type": "object",
            "properties": {
              "cursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              }
            },
            "required": [
              "cursor",
              "next_cursor",
              "limit"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schema_id",
          "as_of",
          "synthetic",
          "org",
          "period",
          "totals",
          "roster",
          "candidates",
          "decisions",
          "share",
          "next_steps",
          "state",
          "state_message",
          "page"
        ],
        "additionalProperties": false
      },
      "DraftContractInput": {
        "type": "object",
        "properties": {
          "template": {
            "type": "string",
            "enum": [
              "support_triage",
              "sdr_qualification",
              "internal_assistant",
              "coding_patch"
            ]
          },
          "agent_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "workload": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "owner": {
            "type": "string",
            "minLength": 1,
            "maxLength": 320
          },
          "objective": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "unit_of_work": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "budget_usd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000000
          },
          "budget_period": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly"
            ]
          },
          "human_baseline": {
            "type": "object",
            "properties": {
              "cost_per_unit_usd": {
                "type": "number",
                "minimum": 0,
                "maximum": 1000000
              },
              "minutes_per_unit": {
                "anyOf": [
                  {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100000
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "basis": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "required": [
              "cost_per_unit_usd",
              "basis"
            ],
            "additionalProperties": false
          },
          "notes": {
            "type": "string",
            "maxLength": 2000
          }
        },
        "required": [
          "template",
          "owner"
        ],
        "additionalProperties": false
      },
      "VendorBillCheckInput": {
        "type": "object",
        "properties": {
          "period": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "from",
              "to"
            ],
            "additionalProperties": false
          },
          "billed": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "external_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "billed_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "cost_usd": {
                  "type": "number",
                  "minimum": -1000000,
                  "maximum": 1000000
                },
                "tier_name": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 100
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "adjustment_of": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 200
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "external_id",
                "billed_at",
                "cost_usd"
              ],
              "additionalProperties": false
            },
            "maxItems": 500
          },
          "resolved_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "maxItems": 2000,
            "default": []
          },
          "rejected_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "maxItems": 2000,
            "default": []
          },
          "ledger": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "external_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "event_type": {
                  "type": "string",
                  "enum": [
                    "solved",
                    "closed",
                    "reopened",
                    "public_comment"
                  ]
                },
                "occurred_at": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "external_id",
                "event_type",
                "occurred_at"
              ],
              "additionalProperties": false
            },
            "maxItems": 2000,
            "default": []
          },
          "import_rejected_count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "default": 0
          },
          "covered_spans": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "from": {
                  "type": "string",
                  "format": "date-time"
                },
                "to": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            "maxItems": 100,
            "default": []
          }
        },
        "required": [
          "period",
          "billed"
        ],
        "additionalProperties": false
      },
      "CostPerResolutionInput": {
        "type": "object",
        "properties": {
          "bill_total": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000000
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$"
          },
          "billed_resolutions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000
          },
          "period": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              }
            },
            "required": [
              "from",
              "to"
            ],
            "additionalProperties": false
          },
          "vendor": {
            "type": "string",
            "maxLength": 100
          },
          "vendor_resolved_definition": {
            "type": "string",
            "maxLength": 2000
          },
          "total_conversations": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000000
          }
        },
        "required": [
          "bill_total",
          "billed_resolutions",
          "period"
        ],
        "additionalProperties": false
      }
    }
  }
}