{
  "openapi": "3.1.0",
  "info": {
    "title": "Amdahl Platform API",
    "version": "1.0.0",
    "description": "REST API for Amdahl customer intelligence. Two surfaces: **Search** — the synchronous fast-search lane over your customer conversations — and **Agents** — the async automation surface (multi-turn Chat, a reusable agent library, and cron-driven Routines)."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "conversations",
      "description": ""
    },
    {
      "name": "data",
      "description": "Data exploration - SQL queries, hybrid search, and ML clusters."
    },
    {
      "name": "observability",
      "description": "Audit logs and execution telemetry."
    },
    {
      "name": "workflows",
      "description": "Workflow orchestration endpoints."
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Platform API key (amdhl_...). Scopes are enforced per operation. The same key is also accepted as `Authorization: Bearer <key>` — one key works on both transports."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer credential: an API key (amdhl_-prefixed values are validated as API keys), an OAuth access token, or a Supabase JWT. Role + scope enforcement applies."
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth2 authorization code flow with scope granularity.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "/api/platform/v1/oauth/authorize",
            "tokenUrl": "/api/platform/v1/oauth/token",
            "scopes": {
              "artifacts:read": "Read artifacts",
              "artifacts:write": "Create and update artifacts",
              "artifacts:delete": "Archive and delete artifacts",
              "context:read": "Read business context and substrate",
              "context:write": "Write evidence and observations",
              "data:read": "Query and search data sources",
              "data:write": "Materialize data assets",
              "team:read": "Read team members",
              "team:write": "Manage team members",
              "webhooks:read": "List webhooks",
              "webhooks:write": "Register and delete webhooks",
              "observability:read": "Read audit logs",
              "config:read": "Read tenant configuration",
              "config:write": "Write tenant configuration",
              "platform:read": "Read platform-level resources",
              "platform:write": "Write platform-level resources"
            }
          }
        }
      }
    },
    "schemas": {
      "Session": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "business_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "business_id",
          "user_id",
          "created_at",
          "updated_at"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "SessionListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at"
        ]
      },
      "DeletedResponse": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean"
          }
        },
        "required": [
          "deleted"
        ]
      },
      "ExploreRequest": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "all",
              "schema",
              "clusters",
              "knowledge"
            ],
            "default": "all"
          },
          "include_samples": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "QueryResult": {
        "type": "object",
        "properties": {
          "rowCount": {
            "type": "number"
          },
          "truncated": {
            "type": "boolean"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "rowCount",
          "truncated",
          "rows"
        ]
      },
      "QueryRequest": {
        "type": "object",
        "properties": {
          "sql": {
            "type": "string",
            "minLength": 1,
            "example": "SELECT company_name, COUNT(*) as cnt FROM interactions GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 100
          }
        },
        "required": [
          "sql"
        ]
      },
      "SearchResults": {
        "type": "object",
        "properties": {
          "resultCount": {
            "type": "number"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "origin": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "snippets": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "id",
                "title",
                "origin",
                "snippets"
              ]
            }
          }
        },
        "required": [
          "resultCount",
          "results"
        ]
      },
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "mode": {
            "type": "string",
            "enum": [
              "hybrid",
              "semantic",
              "keyword"
            ],
            "default": "hybrid"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          },
          "source_type": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ]
      },
      "ClusterSearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "match_threshold": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          }
        },
        "required": [
          "query"
        ]
      },
      "SubstrateIntent": {
        "type": "string",
        "enum": [
          "answer_question",
          "find_metrics",
          "research_overview",
          "summarize_research",
          "evidence_for_writing",
          "enrich_with_quotes",
          "assess_viability"
        ]
      },
      "SubstrateQueryRequest": {
        "type": "object",
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/SubstrateIntent"
          },
          "query": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "source_filter": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "intent"
        ]
      },
      "AskResponse": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string"
          },
          "substrateStats": {
            "type": "object",
            "properties": {
              "evidenceSearched": {
                "type": "number"
              },
              "clustersSearched": {
                "type": "number"
              },
              "metricsAvailable": {
                "type": "number"
              }
            },
            "required": [
              "evidenceSearched",
              "clustersSearched",
              "metricsAvailable"
            ]
          }
        },
        "required": [
          "answer",
          "substrateStats"
        ]
      },
      "AskRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "query"
        ]
      },
      "RememberResponse": {
        "type": "object",
        "properties": {
          "evidenceId": {
            "type": "string"
          },
          "totalEvidenceCount": {
            "type": "number"
          },
          "persisted": {
            "type": "boolean",
            "description": "Whether the substrate was durably persisted to DB"
          }
        },
        "required": [
          "evidenceId",
          "totalEvidenceCount",
          "persisted"
        ]
      },
      "RememberRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          },
          "source": {
            "type": "string",
            "enum": [
              "web",
              "kg",
              "reference_doc",
              "bigquery",
              "cluster"
            ],
            "default": "web"
          },
          "company_name": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "text"
        ]
      },
      "WebhookEvent": {
        "type": "string",
        "enum": [
          "artifact.created",
          "artifact.updated",
          "artifact.status_changed",
          "session.completed"
        ]
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "business_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "active": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "secret": {
            "type": "string",
            "description": "Only returned on creation"
          }
        },
        "required": [
          "id",
          "business_id",
          "user_id",
          "url",
          "events",
          "active",
          "created_at"
        ]
      },
      "RegisterWebhookRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            },
            "minItems": 1
          }
        },
        "required": [
          "url",
          "events"
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "webhook_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "event": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "additionalProperties": {}
          },
          "status_code": {
            "type": [
              "number",
              "null"
            ]
          },
          "attempt": {
            "type": "integer"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "webhook_id",
          "event",
          "payload",
          "status_code",
          "attempt",
          "error",
          "created_at"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/platform/v1/agents/{session_id}/resume": {
      "post": {
        "operationId": "agentsResume",
        "summary": "Resume Agent Session",
        "description": "Resume an agent run that is paused on pending user input. Use when replying to an outline approval prompt, a clarification question, or a continue/finish decision. The input payload must match the run's `pending_input_schema`. After a successful resume the run transitions back to running and proceeds from where it paused.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "workflows:write"
            ]
          },
          {
            "BearerAuth": [
              "workflows:write"
            ]
          }
        ],
        "x-scopes": [
          "workflows:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "object",
                    "description": "The user's resume payload. Must match the run's persisted pending_input_schema.",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "input"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/agents/{session_id}/cancel": {
      "post": {
        "operationId": "agentsCancel",
        "summary": "Cancel Agent Session",
        "description": "Cancel an in-flight agent run. Use when the user wants to stop a running agent before it finishes, or abandon a run that has gone sideways. Cascades to any sub-agents spawned from this run via agents.start — every live descendant is cancelled atomically. The runner bails at the next iteration boundary after observing the status change. Already-completed runs cannot be canceled. Pass a reason to record WHY the run was aborted in the audit trail.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "workflows:write"
            ]
          },
          {
            "BearerAuth": [
              "workflows:write"
            ]
          }
        ],
        "x-scopes": [
          "workflows:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional operator note describing why the run was canceled."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/agents": {
      "get": {
        "operationId": "agentsListAgents",
        "summary": "List Workspace Agents",
        "description": "List the workspace agent roster - Amdahl-shipped library agents merged with tenant-authored ones - as lean rows of slug, name, description, and provenance. Read when choosing which named agent should handle a task or rendering the agent directory. Library entries are code-defined and locked; tenant rows carry their creation time.",
        "tags": [
          "workflows"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:read"
            ]
          },
          {
            "BearerAuth": [
              "agents:read"
            ]
          }
        ],
        "x-scopes": [
          "agents:read"
        ],
        "x-stability": "stable"
      },
      "post": {
        "operationId": "agentsCreateAgent",
        "summary": "Create Workspace Agent",
        "description": "Save a new tenant-authored agent: a named, reusable prompt the workspace can dispatch later by its stable kebab-case slug. Use when a user wants to capture a custom instruction set as a workspace agent. Rejects a slug that shadows an Amdahl library agent (those ship in code and cannot be replaced) and surfaces tenant slug collisions as a typed conflict.",
        "tags": [
          "workflows"
        ],
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:write"
            ]
          },
          {
            "BearerAuth": [
              "agents:write"
            ]
          }
        ],
        "x-scopes": [
          "agents:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 64,
                    "description": "Optional stable kebab-case dispatch key (lowercase letters, digits, single dashes). Omitted: derived from the name and uniquified automatically."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "Display name."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Optional one-line blurb for the agent directory."
                  },
                  "tool_blocklist": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 120
                    },
                    "maxItems": 100,
                    "description": "Operation ids to subtract from this agent tool kit at run time (all kit tools are on by default; empty list = no restriction). Runner-inline tools are refused."
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The prompt the agent runs with."
                  }
                },
                "required": [
                  "name",
                  "prompt"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/agents/{id}": {
      "get": {
        "operationId": "agentsGetAgent",
        "summary": "Get Agent By Id Or Slug",
        "description": "Fetch one named agent by slug or id, including the full prompt text it runs with. Resolves the Amdahl code library first, then falls back to the tenant row. Read when inspecting exactly what instructions an agent carries before dispatching, editing, or duplicating it. Returns null for another tenant or a missing id.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "UUID or slug of the agent to read.",
            "schema": {
              "type": "string",
              "description": "UUID or slug of the agent to read."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:read"
            ]
          },
          {
            "BearerAuth": [
              "agents:read"
            ]
          }
        ],
        "x-scopes": [
          "agents:read"
        ],
        "x-stability": "stable"
      },
      "patch": {
        "operationId": "agentsUpdateAgent",
        "summary": "Update Workspace Agent",
        "description": "Revise a tenant-authored agent's name, description, or prompt in place, keeping its slug stable. Call when refining how a saved agent behaves after seeing its output. Amdahl library agents are code-defined and immutable, so edits targeting one are refused with a locked error rather than silently ignored.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "UUID or slug of the agent to patch.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "UUID or slug of the agent to patch."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:write"
            ]
          },
          {
            "BearerAuth": [
              "agents:write"
            ]
          }
        ],
        "x-scopes": [
          "agents:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "New display name."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "New directory blurb."
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "description": "New prompt body."
                  },
                  "tool_blocklist": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 120
                    },
                    "maxItems": 100,
                    "description": "Operation ids to subtract from this agent tool kit at run time (all kit tools are on by default; empty list = no restriction). Runner-inline tools are refused."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "agentsDeleteAgent",
        "summary": "Archive Workspace Agent",
        "description": "Retire a tenant-authored agent by soft-archiving it out of the roster; the row is retained and nothing is destroyed. Use when the workspace no longer dispatches a saved agent. Archived agents disappear from listings immediately, while Amdahl library agents cannot be archived at all - they are code-defined and always available.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "UUID or slug of the agent to archive.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "UUID or slug of the agent to archive."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:write"
            ]
          },
          {
            "BearerAuth": [
              "agents:write"
            ]
          }
        ],
        "x-scopes": [
          "agents:write"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/agents/usage": {
      "get": {
        "operationId": "agentsGetBuildUsage",
        "summary": "Get Build Usage",
        "description": "Workspace rollups of recent agent and routine activity over a fixed 30-day window: per-agent and per-routine run counts (7d / 30d), last run pointers, schedule counts, and workspace totals. Read when rendering the Agents & Routines page so operators can see which specialists and schedules are doing anything without inspecting each chat.",
        "tags": [
          "workflows"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "agents:read"
            ]
          },
          {
            "BearerAuth": [
              "agents:read"
            ]
          }
        ],
        "x-scopes": [
          "agents:read"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/chat": {
      "post": {
        "operationId": "chatStart",
        "summary": "Chat",
        "description": "Ask the workspace anything: opens or continues a named Chat and enqueues one Master agent turn. Use when starting an investigation over company data, memory, and connected sources. Always returns handles immediately (chat_id, run_id, stream/read/resume URLs) - subscribe to stream_url or poll read_url with wait_ms for the answer; never blocks.",
        "tags": [
          "conversations"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:write"
            ]
          },
          {
            "BearerAuth": [
              "conversations:write"
            ]
          }
        ],
        "x-scopes": [
          "conversations:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32000,
                    "description": "The ask, in plain language. Becomes the Master turn user message."
                  },
                  "chat_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Continue an existing Chat. Omit to open a new one."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "Name for a NEW Chat. Omitted: auto-titled from the input."
                  },
                  "agent": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Optional agent pin: an Amdahl library slug/uuid or workspace agent id/slug the Master turn runs as (Master privileges; the agent prompt is the specialization)."
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "depth": {
                        "type": "string",
                        "enum": [
                          "quick",
                          "standard",
                          "deep"
                        ]
                      },
                      "actions_allowed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 20,
                        "description": "Outbound actions this run may invoke. Absent = ALL cataloged actions (default ON); pass a list to narrow, [] to disable."
                      },
                      "write_outputs": {
                        "type": "boolean",
                        "description": "Allow living-doc commits. Default false."
                      },
                      "write_memory": {
                        "type": "boolean",
                        "description": "Allow long-term memory commits. Default false on API keys."
                      },
                      "on_question": {
                        "type": "string",
                        "enum": [
                          "pause",
                          "auto",
                          "none"
                        ],
                        "description": "ask_a_human behavior: pause (interactive), auto (default), none (headless)."
                      },
                      "external_search": {
                        "type": "boolean",
                        "description": "Allow market fan-outs (external_search.execute stays in the kit). Default false; deep depth forces true."
                      },
                      "include_divergence": {
                        "type": "boolean",
                        "description": "Fuse the divergence map on external_search.execute (else mode:evidence). Default false; deep depth forces true."
                      }
                    },
                    "additionalProperties": false,
                    "description": "The only knobs. No model, temperature, or stream fields exist."
                  }
                },
                "required": [
                  "input"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/chats": {
      "get": {
        "operationId": "chatList",
        "summary": "List Chats",
        "description": "List Chats for this workspace, newest activity first. Read when picking a Chat to continue, rendering a recents rail, or reviewing what one agent or routine has been doing. Each entry is a lean snapshot (name, status, turn count, last activity, and how it was triggered); scope by agent_ref or routine_id, filter by status, page via limit and offset.",
        "tags": [
          "conversations"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          {
            "name": "agent_ref",
            "in": "query",
            "required": false,
            "description": "Keep only Chats this agent drove (slug or uuid — both forms of the same agent match).",
            "schema": {
              "type": "string",
              "description": "Keep only Chats this agent drove (slug or uuid — both forms of the same agent match)."
            }
          },
          {
            "name": "routine_id",
            "in": "query",
            "required": false,
            "description": "Keep only Chats this routine fired.",
            "schema": {
              "type": "string",
              "description": "Keep only Chats this routine fired."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:read"
            ]
          },
          {
            "BearerAuth": [
              "conversations:read"
            ]
          }
        ],
        "x-scopes": [
          "conversations:read"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/chats/{id}": {
      "get": {
        "operationId": "chatGet",
        "summary": "Get Chat",
        "description": "Fetch one Chat snapshot: name, status, its runs (with read handles), which runs are still in flight, and any pending human asks with their resume URLs. Read when rendering a Chat view, deciding whether to continue it, or surfacing an awaiting question to the human. Returns null for unknown or cross-workspace ids.",
        "tags": [
          "conversations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:read"
            ]
          },
          {
            "BearerAuth": [
              "conversations:read"
            ]
          }
        ],
        "x-scopes": [
          "conversations:read"
        ],
        "x-stability": "stable"
      },
      "patch": {
        "operationId": "chatRename",
        "summary": "Rename Chat",
        "description": "Rename one Chat so the thread is findable later. Use when a chat was auto-titled from its first ask and deserves a human name, or when its focus shifted. Renames the underlying conversation title in place; runs, substrate, and handles are untouched. Returns the updated chat snapshot.",
        "tags": [
          "conversations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Chat UUID.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Chat UUID."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:write"
            ]
          },
          {
            "BearerAuth": [
              "conversations:write"
            ]
          }
        ],
        "x-scopes": [
          "conversations:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120,
                    "description": "The new chat name."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/chats/{id}/runs/{run_id}": {
      "get": {
        "operationId": "chatGetRun",
        "summary": "Get Chat Run",
        "description": "Read one Chat run snapshot: status, pause payload when awaiting input, the answer envelope (answer_text plus the ordered content_blocks with query and snapshot data), answered asks, and usage. Read when polling a started Chat for its result; pass wait_ms (max 30000) to long-poll until the run settles instead of tight-looping. Pass include=events to also get the persisted activity trace for transcript replay.",
        "tags": [
          "conversations"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Chat (conversation) UUID.",
            "schema": {
              "type": "string",
              "description": "Chat (conversation) UUID."
            }
          },
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "description": "Run (turn) UUID from the START response.",
            "schema": {
              "type": "string",
              "description": "Run (turn) UUID from the START response."
            }
          },
          {
            "name": "wait_ms",
            "in": "query",
            "required": false,
            "description": "Optional long-poll budget in ms; hard-capped at 30000.",
            "schema": {
              "type": "integer",
              "description": "Optional long-poll budget in ms; hard-capped at 30000."
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Optional: 'events' includes the persisted activity trace (parent + sub-agent tool calls, capped) so a reloaded transcript can replay what the run did.",
            "schema": {
              "type": "string",
              "description": "Optional: 'events' includes the persisted activity trace (parent + sub-agent tool calls, capped) so a reloaded transcript can replay what the run did."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:read"
            ]
          },
          {
            "BearerAuth": [
              "conversations:read"
            ]
          }
        ],
        "x-scopes": [
          "conversations:read"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/chat/preferences": {
      "get": {
        "operationId": "chatGetPreferences",
        "summary": "Get Chat Preferences",
        "description": "Fetch the calling user's saved Chat settings for this workspace: their default run-config knobs (depth, on_question, write_outputs/memory, external_search, include_divergence, actions_allowed) and their agent block list. Read when opening the Chat settings surface to seed its controls. Returns defaults when nothing is saved yet.",
        "tags": [
          "conversations"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:read"
            ]
          },
          {
            "BearerAuth": [
              "conversations:read"
            ]
          }
        ],
        "x-scopes": [
          "conversations:read"
        ],
        "x-stability": "stable"
      },
      "patch": {
        "operationId": "chatUpdatePreferences",
        "summary": "Update Chat Preferences",
        "description": "Save the calling user's Chat settings for this workspace: their default run-config knobs and/or their agent block list (the agents the Master may not delegate to). Use when the user changes a control in the Chat settings surface. A top-level PATCH — only the keys you send change; the block list applies to new Chat turns server-side.",
        "tags": [
          "conversations"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "conversations:write"
            ]
          },
          {
            "BearerAuth": [
              "conversations:write"
            ]
          }
        ],
        "x-scopes": [
          "conversations:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "run_config": {
                    "type": "object",
                    "properties": {
                      "depth": {
                        "type": "string",
                        "enum": [
                          "quick",
                          "standard",
                          "deep"
                        ]
                      },
                      "actions_allowed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 20
                      },
                      "write_outputs": {
                        "type": "boolean"
                      },
                      "write_memory": {
                        "type": "boolean"
                      },
                      "on_question": {
                        "type": "string",
                        "enum": [
                          "pause",
                          "auto",
                          "none"
                        ]
                      },
                      "external_search": {
                        "type": "boolean"
                      },
                      "include_divergence": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": false,
                    "description": "Default Chat run knobs. Replaces the stored run_config wholesale when sent."
                  },
                  "blocked_agents": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "maxItems": 200,
                    "description": "Agent slugs / refs the Master may NOT delegate to for this user. Empty = every agent usable."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/search/query": {
      "post": {
        "operationId": "searchQuery",
        "summary": "Routed Warehouse Search",
        "description": "One routed door over tenant warehouse data: each ask lands on typed filters, an NL-to-SQL pass, or vector similarity. Use when you hold a plain question OR typed predicates and want the cheapest lane picked automatically (force one via mode). Returns the lane, rows, any compiled SQL, and retry_guidance naming the exact params to re-send when part of a multi-part ask went unanswered. Act on retry_guidance instead of giving up. Lanes read different stores at different grains — read corpus.",
        "tags": [
          "data"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "mode_ran": {
                          "type": "string"
                        },
                        "results": {
                          "type": "array"
                        },
                        "compiled": {
                          "type": "object"
                        },
                        "freshness": {
                          "type": "object"
                        },
                        "corpus": {
                          "type": "object"
                        },
                        "timing": {
                          "type": "object"
                        },
                        "cached": {
                          "type": "boolean"
                        },
                        "detail": {
                          "type": "object"
                        },
                        "job": {
                          "type": "object"
                        },
                        "error": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "data:read"
            ]
          },
          {
            "BearerAuth": [
              "data:read"
            ]
          }
        ],
        "x-scopes": [
          "data:read"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Free-text ask. Meaning-shaped wording (\"what do customers say about…\") routes to the semantic lane; other questions route to the NL-to-SQL fuzzy lane."
                  },
                  "max_subqueries": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 12,
                    "description": "How many independent sub-questions a multi-part ask may fan out into. Default 3; up to 5 synchronously and 12 with async:true. RAISE THIS when a reply comes back with retry_guidance.action = \"raise_max_subqueries\" — it means parts of your question were cut by this cap, and retry_guidance.suggested_params carries the value to use."
                  },
                  "async": {
                    "type": "boolean",
                    "description": "Run as a background job instead of blocking. Returns {job:{job_id,status}} straight away; collect it by calling this verb again with that job_id and no query. USE THIS when a reply comes back with retry_guidance.action = \"run_async\" — the synchronous path is bounded at ~15s and your ask needs longer, and the async path also allows a higher max_subqueries. Prefer it for any deliberately broad, multi-part question."
                  },
                  "job_id": {
                    "type": "string",
                    "description": "Collect a job started with async:true. Send this ALONE (no query). While status is \"queued\"/\"running\", poll again; on \"complete\" the full envelope is on detail."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "filter",
                      "fuzzy",
                      "semantic"
                    ],
                    "description": "Lane override. Default auto: filters-with-no-query → filter; meaning-shaped query → semantic; else fuzzy. Lanes read DIFFERENT stores at different grains — read `corpus` on the response to see which one answered."
                  },
                  "surface": {
                    "type": "string",
                    "enum": [
                      "interactions",
                      "deals",
                      "deal_qualification"
                    ],
                    "description": "Warehouse surface for the filter lane. Default interactions. Ignored by the fuzzy and semantic lanes, which report it back in corpus.ignored_params when you pass it."
                  },
                  "audience": {
                    "type": "string",
                    "enum": [
                      "all",
                      "customer_voice"
                    ],
                    "description": "Who counts as the voice you want. Default \"all\". Use \"customer_voice\" to keep only genuine customer / prospect speech and drop investor, advisor, media, partner, vendor and competitor chatter that merely shares an account record — while STILL keeping a real buyer on such an account (someone on a live opportunity, or a scored champion / economic buyer). This applies the platform's own canonical rule server-side; it is a disjunction you cannot express with `filters`, which are ANDed. interactions only."
                  },
                  "hydrate": {
                    "type": "boolean",
                    "description": "Semantic lane only. Semantic matches carry a truncated preview and no labels, so they cannot be quoted or attributed. Set true to bridge each match back to its full warehouse row — full `content` plus company, speaker title, pushback and buyer-signal columns. One row per match, containing the matched utterance, so a hit is citable. SPEAKER comes from the ATOMIC utterance that matched, not from the turn stamp: read speaker_attribution on each row. \"utterance\" = verified from the atomic source. \"ambiguous\" = two matched utterances share this row and disagree on speaker, so the speaker fields are NULL and nobody is named — check turn_speakers for who is in play. \"turn\" = the atomic source had no row, so the fields are the turn's FIRST member and are NOT verified. Separately, speaker_ambiguous says the row's TEXT spans more than one speaker (13.58% of turns on the tenant measured 2026-08-15) — a row can be cleanly attributed AND span two voices, so quoting the whole content as one person is still wrong there. Both fields ship on every turn-grain row including the clean ones; corpus.speaker_ambiguous_rows / corpus.speaker_unattributable_rows are the rates. speaker_ambiguous_source says where that verdict came from: \"stamped\" = read from the column the pipeline writes on the turn itself, \"overlay\" = reconstructed at read time because the pipeline recorded none for that turn. A missing record is NOT \"one speaker\" — permanently-excluded interactions never get one — so an unrecorded turn falls back rather than being reported unambiguous, and a \"stamped\" row also carries speaker_count. corpus.speaker_stamped_rows / corpus.speaker_fallback_rows are the split. Stakeholder columns (role_level, is_champion, is_economic_buyer, champion_score, inferred_persona) are derived from the turn stamp, so they are NULLED when the row is re-attributed to a different speaker rather than left describing someone else. Slower — two reads. Check corpus.hydrated_grain: \"turn\" is that row-per-match answer; \"call\" means the turn lookup failed and the rows are arbitrary turns from the right conversations (context, not the matches; also flagged corpus.degraded). Matches whose utterance belongs to no turn have no warehouse row and are counted in corpus.unresolved_matches; matches sharing one turn are corpus.collapsed_matches. Read those two directly rather than inferring a gap from a match_count/row_count delta — corpus.match_count is how many nearest neighbours the lane pulled and is BOUNDED BY limit, not a count of how many things genuinely matched. Caps at 200 distinct ids, reported as corpus.truncated."
                  },
                  "coverage": {
                    "type": "boolean",
                    "description": "Opt into gap detection on corpus.coverage. Every response ALREADY carries corpus.coverage with max_timestamp / min_timestamp and an age histogram, computed free from the rows returned. This flag adds `gaps`: windows where the corpus HELD rows and this result set had none — the \"your evidence has a hole in it\" signal, as opposed to the ordinary quiet periods a plain empty-bucket scan would flag. Costs one extra bucketed read, so it is off by default. Read coverage.basis first: \"matched_set\" means the numbers describe your whole match set, \"returned_rows\" means they describe a truncated slice, and \"unavailable\" means coverage could not be measured — never read that as zero."
                  },
                  "filters": {
                    "type": "array",
                    "maxItems": 32,
                    "items": {
                      "type": "object",
                      "properties": {
                        "field": {
                          "type": "string",
                          "description": "A field from search_field://list."
                        },
                        "op": {
                          "type": "string",
                          "enum": [
                            "eq",
                            "neq",
                            "in",
                            "not_in",
                            "contains",
                            "gt",
                            "gte",
                            "lt",
                            "lte",
                            "between",
                            "is_null",
                            "not_null"
                          ]
                        },
                        "value": {
                          "description": "Scalar for eq/neq/gt/gte/lt/lte/contains; array for in/not_in; [low, high] for between; omitted for is_null/not_null."
                        }
                      },
                      "required": [
                        "field",
                        "op"
                      ],
                      "additionalProperties": false
                    },
                    "description": "Typed predicates (ANDed — there is no OR; for the customer-voice disjunction use `audience`). Semantic mode supports only company_id / occurred_at / speaker_type, and cannot apply any of them on its theme-index fallback — check corpus.filters_applied. The filter lane supports every field the catalog advertises."
                  },
                  "order_by": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "dir": {
                        "type": "string",
                        "enum": [
                          "asc",
                          "desc"
                        ]
                      }
                    },
                    "required": [
                      "field",
                      "dir"
                    ],
                    "additionalProperties": false,
                    "description": "Filter lane: order by a vocabulary field or a metric alias (e.g. \"count\")."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000,
                    "description": "Row / match cap; hard max 1000. Default is lane-dependent: 100 on the filter and semantic lanes, 50 on the fuzzy lane (where an unforced plain-language question usually lands), so pass it explicitly when the row count matters."
                  },
                  "group_by": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 8,
                    "description": "Filter lane: group fields (requires at least one metric)."
                  },
                  "metrics": {
                    "type": "array",
                    "maxItems": 8,
                    "items": {
                      "type": "object",
                      "properties": {
                        "fn": {
                          "type": "string",
                          "enum": [
                            "count",
                            "count_distinct",
                            "sum",
                            "avg",
                            "min",
                            "max"
                          ]
                        },
                        "field": {
                          "type": "string",
                          "description": "Required for every fn except count."
                        }
                      },
                      "required": [
                        "fn"
                      ],
                      "additionalProperties": false
                    },
                    "description": "Filter lane: aggregations (sum/avg need a numeric field)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/search/fields": {
      "get": {
        "operationId": "searchFields",
        "summary": "Search Filter Fields",
        "description": "Read when composing typed predicates for the routed search verb: the per-surface field catalog (interactions, deals, deal_qualification) listing each field with its type, description, and the comparison operators it admits. Derived live from the warehouse schema catalog - exactly what the filter compiler validates against, so it can never drift from the accepted vocabulary.",
        "tags": [
          "data"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "data:read"
            ]
          },
          {
            "BearerAuth": [
              "data:read"
            ]
          }
        ],
        "x-scopes": [
          "data:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/routines": {
      "post": {
        "operationId": "routinesCreate",
        "summary": "Create Routine",
        "description": "Create a Routine: a cron that fires a Chat each occurrence, running one Master agent turn in a fresh named Chat. Use when the user asks for a standing refresh or a recurring investigation. Provide name, prompt, and cron (plus optional timezone and per-fire config like write_outputs or an agents roster); the fire never pauses on a human and each occurrence opens a new Chat.",
        "tags": [
          "workflows"
        ],
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:write"
            ]
          },
          {
            "BearerAuth": [
              "routines:write"
            ]
          }
        ],
        "x-scopes": [
          "routines:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Human label. Each fired Chat is named \"{name} — {date}\"."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "The Chat input every fire starts the Master turn with."
                  },
                  "cron": {
                    "type": "string",
                    "description": "Cron expression (e.g. \"0 9 * * 1\"). Validated before the row is stored."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone the cron evaluates in. Defaults to UTC."
                  },
                  "agent": {
                    "type": "string",
                    "description": "LEGACY single-agent pin the Master turn runs as (library slug/uuid or workspace agent id/slug). Prefer config.agents; passing both rejects."
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "depth": {
                        "type": "string",
                        "enum": [
                          "quick",
                          "standard",
                          "deep"
                        ]
                      },
                      "agents": {
                        "description": "Agents the routine employs: \"all\" for unrestricted delegation, one ref to run AS that agent (pin), or several refs to restrict delegation to that roster.",
                        "anyOf": [
                          {
                            "type": "string",
                            "enum": [
                              "all"
                            ]
                          },
                          {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200
                            },
                            "minItems": 1,
                            "maxItems": 20
                          }
                        ]
                      },
                      "actions_allowed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 20,
                        "description": "Outbound actions each fired run may invoke. Absent = ALL cataloged actions (default ON); pass a list to narrow, [] to disable."
                      },
                      "write_outputs": {
                        "type": "boolean",
                        "description": "Allow living-doc commits from fired runs. Default true for routines."
                      },
                      "write_memory": {
                        "type": "boolean",
                        "description": "Allow long-term memory commits from fired runs. Default false."
                      },
                      "external_search": {
                        "type": "boolean",
                        "description": "Allow market fan-outs (external_search.execute in the kit). Default false."
                      },
                      "include_divergence": {
                        "type": "boolean",
                        "description": "Fuse the divergence map on external_search.execute (else evidence-only). Default false."
                      }
                    },
                    "additionalProperties": false,
                    "description": "Per-fire Chat config. on_question is always none (headless); write_outputs defaults true for routines; agents picks the roster (\"all\", one pin, or a delegate allowlist)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether the routine fires. Defaults to true."
                  }
                },
                "required": [
                  "name",
                  "prompt",
                  "cron"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      },
      "get": {
        "operationId": "routinesList",
        "summary": "List Routines",
        "description": "List the workspace Routines, newest first: each entry carries the prompt, cadence (cron + timezone), agent pin, per-fire config, and last/next fire bookkeeping. Read when rendering the Routines page, checking what refreshes on a schedule, or picking one to update or fire now. Filter by enabled; paginate via limit + offset.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "description": "Filter by enabled state. As a query param, accepts ONLY the exact strings \"true\" or \"false\"; any other value (or omitted) applies no filter.",
            "schema": {
              "type": "boolean",
              "description": "Filter by enabled state. As a query param, accepts ONLY the exact strings \"true\" or \"false\"; any other value (or omitted) applies no filter."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:read"
            ]
          },
          {
            "BearerAuth": [
              "routines:read"
            ]
          }
        ],
        "x-scopes": [
          "routines:read"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/routines/{id}": {
      "get": {
        "operationId": "routinesGet",
        "summary": "Get Routine",
        "description": "Fetch one Routine in full: prompt, cadence, agent roster, per-fire config, enabled state, and the last fire pointers (Chat + run ids). Read when opening a routine detail view or before patching one. Unknown and cross-workspace ids return null.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:read"
            ]
          },
          {
            "BearerAuth": [
              "routines:read"
            ]
          }
        ],
        "x-scopes": [
          "routines:read"
        ],
        "x-stability": "stable"
      },
      "patch": {
        "operationId": "routinesUpdate",
        "summary": "Update Routine",
        "description": "Patch an existing Routine: rename it, change its prompt or cadence, re-pin the agent, adjust per-fire config, or enable/disable it. Use when tuning a standing scheduled ask without recreating it. Only the supplied fields change; a cadence change is re-validated first and takes effect on the next scheduler tick.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The routine id.",
            "schema": {
              "type": "string",
              "description": "The routine id."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:write"
            ]
          },
          {
            "BearerAuth": [
              "routines:write"
            ]
          }
        ],
        "x-scopes": [
          "routines:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New human label."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "New Chat input for future fires."
                  },
                  "cron": {
                    "type": "string",
                    "description": "New cron expression (validated before storing)."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "New IANA timezone."
                  },
                  "agent": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "LEGACY single-agent pin, or null to clear back to the plain Master. Prefer config.agents; passing both rejects."
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "depth": {
                        "type": "string",
                        "enum": [
                          "quick",
                          "standard",
                          "deep"
                        ]
                      },
                      "agents": {
                        "description": "Agents the routine employs: \"all\" for unrestricted delegation, one ref to run AS that agent (pin), or several refs to restrict delegation to that roster.",
                        "anyOf": [
                          {
                            "type": "string",
                            "enum": [
                              "all"
                            ]
                          },
                          {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 200
                            },
                            "minItems": 1,
                            "maxItems": 20
                          }
                        ]
                      },
                      "actions_allowed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "maxItems": 20,
                        "description": "Outbound actions each fired run may invoke. Absent = ALL cataloged actions (default ON); pass a list to narrow, [] to disable."
                      },
                      "write_outputs": {
                        "type": "boolean",
                        "description": "Allow living-doc commits from fired runs. Default true for routines."
                      },
                      "write_memory": {
                        "type": "boolean",
                        "description": "Allow long-term memory commits from fired runs. Default false."
                      },
                      "external_search": {
                        "type": "boolean",
                        "description": "Allow market fan-outs (external_search.execute in the kit). Default false."
                      },
                      "include_divergence": {
                        "type": "boolean",
                        "description": "Fuse the divergence map on external_search.execute (else evidence-only). Default false."
                      }
                    },
                    "additionalProperties": false,
                    "description": "Replacement per-fire config (replaces the whole object, including the agents roster)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Enable or disable firing."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "routinesDelete",
        "summary": "Delete Routine",
        "description": "Permanently remove a Routine so its cadence stops firing. Use when the user no longer wants the standing scheduled ask. Deletion affects only future fires - Chats and documents earlier fires produced are untouched. Prefer disabling (routines.update enabled=false) when the user may want it back.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The routine id to delete.",
            "schema": {
              "type": "string",
              "description": "The routine id to delete."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:write"
            ]
          },
          {
            "BearerAuth": [
              "routines:write"
            ]
          }
        ],
        "x-scopes": [
          "routines:write"
        ],
        "x-stability": "stable"
      }
    },
    "/api/platform/v1/routines/{id}/run-now": {
      "post": {
        "operationId": "routinesRunNow",
        "summary": "Run Routine Now",
        "description": "Fire one Routine immediately, off-cadence: opens a fresh Chat and starts the Master turn exactly as the cron would. Use when the user wants the standing refresh right now instead of waiting for the next occurrence. Returns the Chat and run handles (stream/read/resume URLs) so the fire can be watched like any Chat.",
        "tags": [
          "workflows"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The routine id to fire.",
            "schema": {
              "type": "string",
              "description": "The routine id to fire."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "routines:write"
            ]
          },
          {
            "BearerAuth": [
              "routines:write"
            ]
          }
        ],
        "x-scopes": [
          "routines:write"
        ],
        "x-stability": "stable",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/evals/run": {
      "post": {
        "operationId": "evalsRun",
        "summary": "Run Eval",
        "description": "Grade content against your workspace data and get a run id to poll. Use when scoring a prompt or a drafted message: pass inputs (prompt and/or message, plus optional audience, account, mode=rewrite|advisory|gate) — a blinded judge scores relevant positioning, grounding, verified specifics, differentiation and CTA clarity against real customer quotes, and the prompt is scored on its own separate rubric. Returns the handle (eval-run://<id>) plus a console_url to give the user.",
        "tags": [
          "observability"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "run_id": {
                          "type": "string"
                        },
                        "reused": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "eval_version": {
                          "type": "string"
                        },
                        "resource": {
                          "type": "string"
                        },
                        "poll": {
                          "type": "object",
                          "description": "How to read the verdict back: action (status), run_id, resource, report_resource, and wait_ms_max - the largest long-poll budget the read honours, so a caller blocks once instead of looping. The run is queued when this returns; it is not the answer yet."
                        },
                        "console_url": {
                          "type": "string",
                          "description": "Link to this run's report in the workspace console. Give it to the user verbatim so they can open the run — run_id and resource are machine addresses they cannot follow. Works immediately (it shows the live grading trail, then the report). Absent when it could not be resolved; never invent one."
                        },
                        "error": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:execute"
            ]
          },
          {
            "BearerAuth": [
              "evals:execute"
            ]
          }
        ],
        "x-scopes": [
          "evals:execute"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "eval": {
                    "type": "string",
                    "description": "Eval slug or id. Default 'prompt-and-message-eval'. Discover options + their input fields via eval://list."
                  },
                  "inputs": {
                    "type": "object",
                    "description": "Run inputs for the eval's declared fields. prompt-and-message-eval requires at least one of prompt / message, and also accepts audience (a seniority or title to scope the cohort), account (the company it is going to — retrieves what THAT account said), and mode: rewrite (the default, a full improved prompt and message), advisory (anchored suggestions against what you wrote), or gate (grade ONLY what you sent and stop — read the verdict from eval-run://<id>/gate). Read the exact schema from eval://<slug>.",
                    "additionalProperties": true
                  },
                  "reuse": {
                    "type": "string",
                    "enum": [
                      "cached",
                      "force"
                    ],
                    "description": "cached (default) reuses an active run for the same target (fingerprint); force always starts a fresh run."
                  },
                  "evidence_from_run": {
                    "type": "string",
                    "description": "Run id whose frozen customer quotes this run should be graded against, instead of retrieving fresh ones. Use to A/B two drafts: without it each run retrieves its own evidence, so the score difference mixes your edit with a different set of quotes. The source run must be in this workspace and have reached retrieval; the report states the pin and how old that evidence is."
                  },
                  "include_external": {
                    "type": "boolean",
                    "description": "Add public web/market evidence to the grade (default false). One web fan-out runs and its snippets join the pool tagged EXTERNAL — the tier that backs market claims (\"analysts report\"), never customer voice. Needs the external_search:execute scope (refused without it, never silently dropped) and cannot combine with a pinned run — a pin holds the evidence frozen, and its pool already carries any external quotes it was graded on."
                  },
                  "external_cap": {
                    "type": "integer",
                    "description": "How many external quotes to retrieve when include_external is set. Clamped to 1..25; default 15. The ack echoes the clamped value as external.cap."
                  },
                  "candidate_from_run": {
                    "type": "string",
                    "description": "Run id whose improved version this run should GRADE, instead of writing a new one. Use to re-run the judge over fixed text — the run makes no generate call, so a score difference between two such runs is the judge, not the writer. Pass reuse=force when sampling: two identical pinned requests share one content address, so on the default reuse=cached the second is served the first run and an N-sample spread reads as zero. Also pins that run's quotes (the citations in the frozen text address them), so pass the same id to evidence_from_run or omit it. Refused if this run submits different copy or a different mode than the pinned candidate was written for."
                  },
                  "scope": {
                    "type": "object",
                    "description": "Narrow WHICH conversations the grade speaks for. Use when the verdict is about a cohort rather than your whole corpus. filters are AND-joined over interactions (utterance grain), deals or deal_qualification (account grain - these resolve to the matching accounts and scope the conversations to them). A slice below the evidence floors (3 speakers, 25 utterances, 2 companies) abstains to whole-corpus grading unless allow_thin_evidence, which grades it anyway and flags below_floors.",
                    "properties": {
                      "filters": {
                        "type": "array",
                        "description": "Typed predicates, AND-joined. At most 25. Read the filterable fields and their operators per surface from the search field catalog.",
                        "items": {
                          "type": "object",
                          "properties": {
                            "surface": {
                              "type": "string",
                              "enum": [
                                "interactions",
                                "deals",
                                "deal_qualification"
                              ]
                            },
                            "field": {
                              "type": "string"
                            },
                            "op": {
                              "type": "string",
                              "enum": [
                                "eq",
                                "neq",
                                "in",
                                "not_in",
                                "contains",
                                "gt",
                                "gte",
                                "lt",
                                "lte",
                                "between",
                                "is_null",
                                "not_null"
                              ]
                            },
                            "value": {}
                          },
                          "required": [
                            "field",
                            "op"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "audience": {
                        "type": "string",
                        "enum": [
                          "all",
                          "customer_voice"
                        ],
                        "description": "customer_voice restricts the slice to buyer speech; all (default) leaves it unrestricted."
                      },
                      "allow_thin_evidence": {
                        "type": "boolean",
                        "description": "Grade the slice even when it falls below the evidence floors, instead of abstaining to the whole corpus. The report carries the real counts and below_floors: true."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/evals": {
      "post": {
        "operationId": "evalsCreate",
        "summary": "Create Eval",
        "description": "Create a custom eval — a configured grading pipeline (declared input fields + cases + graders) stored for your workspace. Use when the built-in graders don't fit and you want your own scored report card. Pass slug, name, input_schema, and cases; the whole definition is validated and you get back the new eval's slug + id, or a structured validation_failed with the exact field errors. Built-in slugs are reserved.",
        "tags": [
          "observability"
        ],
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:write"
            ]
          },
          {
            "BearerAuth": [
              "evals:write"
            ]
          }
        ],
        "x-scopes": [
          "evals:write"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "description": "kebab-case identifier, unique in your workspace."
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string",
                    "description": "semver, default 1.0.0."
                  },
                  "input_schema": {
                    "type": "object",
                    "description": "Declared run-input fields ({ fields: [...] }).",
                    "additionalProperties": true
                  },
                  "cases": {
                    "type": "array",
                    "description": "Cases: each a subject + its graders.",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "reliability": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Required for any grader that reports a MAGNITUDE (judge / evidence_judge / improvement_loop): the measured flip rate and the floor a reported lift must clear. Validation refuses without it, so declare it rather than discovering the refusal."
                  }
                },
                "required": [
                  "slug",
                  "name",
                  "cases"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      },
      "get": {
        "operationId": "evalList",
        "summary": "List Evals",
        "description": "List every eval available to this workspace (prompt-and-message-eval, plus any you authored). Use when choosing which grader to run or rendering an eval picker. Returns slug, name, version, description, input_schema, and case count per eval; fetch eval://<slug> for the full cases + graders.",
        "tags": [
          "observability"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/evals/{slug}": {
      "patch": {
        "operationId": "evalsUpdate",
        "summary": "Update Eval",
        "description": "Revise one of your workspace's authored evals in place. Use when tuning a custom grader's rubric, thresholds, input fields, or cases. Pass the slug plus the fields to change; the merged definition is re-validated before it is stored, returning the slug + version or a structured validation error. Built-in evals cannot be edited.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The authored eval to revise.",
            "schema": {
              "type": "string",
              "description": "The authored eval to revise."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:write"
            ]
          },
          {
            "BearerAuth": [
              "evals:write"
            ]
          }
        ],
        "x-scopes": [
          "evals:write"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "input_schema": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "cases": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "reliability": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Required for any grader that reports a MAGNITUDE (judge / evidence_judge / improvement_loop): the measured flip rate and the floor a reported lift must clear. Validation refuses without it, so declare it rather than discovering the refusal."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "evalsDelete",
        "summary": "Delete Eval",
        "description": "Archive one of your workspace's authored evals so it no longer lists or runs. Use when retiring a custom grader you no longer need; the slug frees up for re-use and a soft archive keeps the audit trail. Pass the slug. Built-in evals cannot be archived. Returns whether a matching eval was found and archived.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:write"
            ]
          },
          {
            "BearerAuth": [
              "evals:write"
            ]
          }
        ],
        "x-scopes": [
          "evals:write"
        ],
        "x-stability": "beta"
      },
      "get": {
        "operationId": "evalGet",
        "summary": "Get Eval",
        "description": "Fetch one eval by slug or id, with its input_schema and full cases — each case subject (a provided input field or a generated target) and the graders (rule checks, system-of-record anchors, judge and evidence-judge rubrics) applied to it. Use when building a run form or inspecting what a grader measures. Returns null for an unknown id.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/evals/validate": {
      "post": {
        "operationId": "evalsValidate",
        "summary": "Validate Eval",
        "description": "Dry-run validate a custom eval definition without storing it. Use when building an eval in a form and you want author-time feedback before saving: it runs the same structural checks as creating one (input-schema shape, subject-to-input-field integrity, per-grader config) and returns valid plus a flat list of path + message errors. Never writes anything.",
        "tags": [
          "observability"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "valid"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "input_schema": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "cases": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "reliability": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Required for any grader that reports a MAGNITUDE (judge / evidence_judge / improvement_loop): the measured flip rate and the floor a reported lift must clear. Validation refuses without it, so declare it rather than discovering the refusal."
                  }
                },
                "required": [
                  "slug",
                  "name",
                  "cases"
                ],
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/evals/export": {
      "post": {
        "operationId": "evalsExport",
        "summary": "Export Eval Runs",
        "description": "Pull this workspace's graded eval runs as flat rows for analysis elsewhere. Use when you need many runs at once rather than one verdict: filter by eval, version, date range, status and verdict, and read back a row per run carrying the score alongside the fields that qualify it. Pass count_only to learn how many runs match — and how many instrument versions they span — before pulling them.",
        "tags": [
          "observability"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "count": {
                          "type": "object",
                          "description": "total, truncated, max_rows, versions (distinct eval_version values in the set), first_run_at and last_run_at. Read `versions` before pooling: more than one means the rows were scored by more than one instrument."
                        },
                        "rows": {
                          "type": "array",
                          "description": "One flat row per run. Every score ships with the fields that qualify it — overall_score with applicable, lift with lift_reportable, the submitted score with input_simulated. A null score is an empty value, never zero."
                        },
                        "scope": {
                          "type": "string",
                          "description": "self (your own runs) or workspace (every run; workspace admins only)."
                        },
                        "error": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "eval": {
                    "type": "string",
                    "description": "Eval slug or id. Default 'prompt-and-message-eval'. Required in effect — columns and versions are per-eval, so one export covers one eval."
                  },
                  "eval_versions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Restrict to these eval_version values. Omit for every version, but read the version spread on the count first: scores from different versions are produced by different instruments and are not comparable."
                  },
                  "from": {
                    "type": "string",
                    "description": "ISO-8601 lower bound on created_at (inclusive)."
                  },
                  "to": {
                    "type": "string",
                    "description": "ISO-8601 upper bound on created_at (exclusive)."
                  },
                  "statuses": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running",
                        "complete",
                        "failed",
                        "canceled"
                      ]
                    },
                    "description": "Restrict to these run statuses. Omit for every status."
                  },
                  "verdicts": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "pass",
                        "partial",
                        "fail",
                        "not_applicable",
                        "ungraded"
                      ]
                    },
                    "description": "Restrict to these verdict buckets. Omit for every bucket. `ungraded` is a pseudo-bucket for runs carrying no verdict at all - the ones whose overall_score cell is empty - so you can isolate or exclude them; it is not a value any run stores."
                  },
                  "count_only": {
                    "type": "boolean",
                    "description": "Return only the count block (total, cap, version spread, date range) without the rows. Cheap enough to call on every filter change."
                  },
                  "redact_quotes": {
                    "type": "boolean",
                    "description": "Blank the verbatim customer quotes in the exported verdict. Affects the raw JSONL download only; the flat rows never carry quote text."
                  },
                  "allow_truncation": {
                    "type": "boolean",
                    "description": "Proceed when more than 5000 runs match, taking the most recent 5000. Without it an over-cap response is refused rather than silently cut. The .csv / .jsonl file downloads stream and have no cap, so they never need this."
                  },
                  "limit": {
                    "type": "number",
                    "description": "Take at most this many runs, most recent first (max 5000 here). A deliberate top-N, not a truncation: it satisfies the cap on its own, so a limited call is never refused for matching a larger set."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/eval-runs/{id}/feedback": {
      "post": {
        "operationId": "evalsRecordFeedback",
        "summary": "Record Eval Feedback",
        "description": "Report what happened AFTER an eval run — whether its recommendation was applied, and how you know. Call when you have acted on a report: rewritten a prompt, filed the improved copy, or decided against it. Requires evidence (did_it_myself | reported_to_me | inferred); report only what you observed, never what you assume a person did. Pass applied_to and the server checks the target actually contains it.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Alias for eval_run_id, carrying the REST path segment. Pass eval_run_id; this exists so POST /eval-runs/:id/feedback resolves.",
            "schema": {
              "type": "string",
              "description": "Alias for eval_run_id, carrying the REST path segment. Pass eval_run_id; this exists so POST /eval-runs/:id/feedback resolves."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "feedback_id": {
                          "type": "string"
                        },
                        "created": {
                          "type": "boolean",
                          "description": "False when this replaced your earlier verdict on the same subject."
                        },
                        "verified": {
                          "type": [
                            "boolean",
                            "null"
                          ],
                          "description": "Three-state. true = the server found the recommendation in applied_to. false = it checked and it is absent. null = nothing was checked. null and false are different answers and must not be collapsed."
                        },
                        "verification_note": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "success"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:execute"
            ]
          },
          {
            "BearerAuth": [
              "evals:execute"
            ]
          }
        ],
        "x-scopes": [
          "evals:execute"
        ],
        "x-stability": "beta",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "eval_run_id": {
                    "type": "string",
                    "description": "The run this feedback is about."
                  },
                  "outcome": {
                    "type": "string",
                    "enum": [
                      "used",
                      "used_with_edits",
                      "not_used",
                      "unsure"
                    ],
                    "description": "What happened to the recommendation. `unsure` is a real answer and is excluded from both halves of any adoption rate — prefer it to guessing."
                  },
                  "evidence": {
                    "type": "string",
                    "enum": [
                      "did_it_myself",
                      "reported_to_me",
                      "inferred"
                    ],
                    "description": "How you know. `did_it_myself` = you performed the action in this session (the only value that can be verified). `reported_to_me` = a person told you. `inferred` = you concluded it; honest, but excluded from published rates. Never claim first-hand knowledge of something a person did outside your session."
                  },
                  "subject_key": {
                    "type": "string",
                    "description": "What the feedback is about. Omit (or '__run__') for the run as a whole; otherwise a stable key naming one recommendation, so the same recommendation across runs can be counted together."
                  },
                  "what_happened": {
                    "type": "string",
                    "description": "Free text, unconstrained. Say what you actually did, or why the recommendation was not usable — the reason is worth more than the verdict."
                  },
                  "applied_to": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Where it was applied, e.g. { \"kind\": \"agent\", \"id\": \"<uuid>\" }. Recognised kinds (agent, routine, knowledge_doc) are dereferenced and checked; anything else is stored unverified rather than rejected."
                  }
                },
                "required": [
                  "outcome",
                  "evidence"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      },
      "get": {
        "operationId": "evalRunFeedback",
        "summary": "Get Eval Run Feedback",
        "description": "Fetch what was reported about one run after the fact: whether its recommendation was applied, how each writer knows, and whether the server could confirm it. Read when deciding whether a past recommendation already landed, or before reporting one as unused. verified is three-state — false means checked and absent, null means nothing checked, and the two are different answers.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The RUN status, mirrored at the root so `data.status` resolves here as it does on every other eval read. The terminal success value is `complete` — never `completed`. It also reads meaningfully here: feedback on a run still `running` is about a recommendation that does not exist yet."
                        },
                        "run_id": {
                          "type": "string"
                        },
                        "feedback": {
                          "type": "array",
                          "description": "One entry per (actor, subject). An actor re-reporting on the same subject replaces their earlier entry; two actors disagreeing appear as two entries, on purpose.",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "summary": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Tallies only — no rate. A ratio over the handful of rows one run collects would be arithmetic on a denominator of two; the rate lives on eval://<slug>/adoption, where it has a population and an abstain floor."
                        }
                      },
                      "required": [
                        "status",
                        "run_id",
                        "feedback",
                        "summary"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/evals/{slug}/kpi": {
      "get": {
        "operationId": "evalKpi",
        "summary": "Get Eval KPI",
        "description": "Fetch the score trend for one eval as a time series over its completed runs: mean submitted-side score per day/week/month, the improved-side ceiling, refusal rate, and the current-vs-prior-window delta. Read when reporting whether writing quality is improving over time. The trend tracks the grade of what callers SUBMITTED, read from verdict.headline so it means one thing across an eval_version bump; windows under 3 scored runs abstain with a named reason rather than assert a mean.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "window_days",
            "in": "query",
            "required": false,
            "description": "Trailing window to aggregate (default 90, clamped 7-365).",
            "schema": {
              "type": "integer",
              "description": "Trailing window to aggregate (default 90, clamped 7-365)."
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/evals/{slug}/adoption": {
      "get": {
        "operationId": "evalAdoption",
        "summary": "Get Eval Adoption",
        "description": "Fetch whether this eval changed anything: how many runs produced a recommendation, how many were reported on, how many were applied, and how often the server could confirm it. Read when asked whether an eval is worth running, or alongside the KPI — a rising score with no adoption means callers improved on their own. Every count states its denominator; the rate abstains rather than assert one on a thin window.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "window_days",
            "in": "query",
            "required": false,
            "description": "Trailing window (default 90, clamped 7-365).",
            "schema": {
              "type": "integer",
              "description": "Trailing window (default 90, clamped 7-365)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "adoption": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Counts, then the rate. `runs_completed` >= `runs_eligible` (refusals and gate-mode runs recommended nothing) >= `runs_with_signal` (someone reported) >= `runs_adopted`. `adoption_rate` is runs_adopted / runs_with_signal, or null with an `abstain_reason` — an abstain (`thin_window`, `no_signal`, `no_eligible_runs`) is never a zero. `counted_evidence` names which evidence values the rate counted; `inferred` is never one of them."
                        }
                      },
                      "required": [
                        "adoption"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs": {
      "get": {
        "operationId": "evalRunList",
        "summary": "List Eval Runs",
        "description": "List this workspace eval runs, newest first, filterable by eval_slug and status (queued|running|complete|failed|canceled). Use when rendering an eval run history or checking whether a report card has finished. Returns lean rows; fetch eval_run://<id> for the full verdict.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "eval_slug",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "full"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}": {
      "get": {
        "operationId": "evalRunGet",
        "summary": "Get Eval Run",
        "description": "Fetch one eval run by id: its status and, once complete, the verdict — verdict.headline carries the grade of the copy the caller SUBMITTED beside the grade of the version the eval wrote, plus the pass/partial/fail bucket and per-case + per-grader detail. Use when polling a run started via evals.run or rendering a report card; pass wait_ms (max 30000) to block until it finishes instead of tight-looping. Returns null for a missing id.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait_ms",
            "in": "query",
            "required": false,
            "description": "Optional long-poll budget in ms, hard-capped at 30000. The read blocks until the run reaches complete / failed / canceled, then returns the SAME body an immediate poll would have returned.",
            "schema": {
              "type": "integer",
              "description": "Optional long-poll budget in ms, hard-capped at 30000. The read blocks until the run reaches complete / failed / canceled, then returns the SAME body an immediate poll would have returned."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The run status, mirrored at the ROOT so `data.status` resolves here exactly as it does on POST /evals/run and on /gate, /drafts, /improvement, /evidence. Identical to `run.status`, which is retained. The terminal success value is `complete` — never `completed`."
                        },
                        "run": {
                          "type": "object",
                          "description": "The run row. Null is returned for a missing or cross-tenant id — the two are deliberately indistinguishable.",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "eval_slug": {
                              "type": "string"
                            },
                            "eval_version": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "queued",
                                "running",
                                "complete",
                                "failed",
                                "canceled"
                              ],
                              "description": "Lifecycle state. The terminal success value is `complete` — never `completed`."
                            },
                            "verdict": {
                              "type": "object",
                              "description": "The graded report card. Null until the run reaches `complete`."
                            },
                            "error_message": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "created_at": {
                              "type": "string"
                            },
                            "finished_at": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "required": [
                            "id",
                            "status"
                          ],
                          "additionalProperties": false
                        },
                        "regrade": {
                          "type": "object",
                          "description": "Present exactly when this run’s evidence pool is pinnable: the parameter set that holds it fixed for the next call. Absent otherwise, never partial."
                        }
                      },
                      "required": [
                        "run",
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/compare/{other_id}": {
      "get": {
        "operationId": "evalRunCompare",
        "summary": "Compare Eval Runs",
        "description": "Compare two eval runs and report whether their difference is a result. Read when A/B-ing two drafts: each run retrieves its own quotes unless pinned, and a bumped eval_version re-means the stored score, so a raw difference can be either rather than your edit. Returns both verdicts, the shared-evidence overlap, any version boundary crossed, and a delta ONLY when the pair supports one — otherwise why not, and how to fix it.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The baseline run id.",
            "schema": {
              "type": "string",
              "description": "The baseline run id."
            }
          },
          {
            "name": "other_id",
            "in": "path",
            "required": true,
            "description": "The candidate run id to compare against it.",
            "schema": {
              "type": "string",
              "description": "The candidate run id to compare against it."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "comparison": {
                          "type": "object",
                          "description": "The comparison. Null is never returned — a missing or cross-tenant id on either side resolves the whole read to a 404, so a compare cannot be used to probe which run ids exist in another workspace.",
                          "properties": {
                            "a": {
                              "type": "object",
                              "description": "The baseline run, with its own status and scores."
                            },
                            "b": {
                              "type": "object",
                              "description": "The candidate run, same shape."
                            },
                            "evidence_overlap": {
                              "type": "object",
                              "description": "How much of the two runs’ quote pools was shared."
                            },
                            "delta_attributable": {
                              "type": "boolean",
                              "description": "Whether the difference can be attributed to the change in graded content. FALSE whenever shared evidence could not be DEMONSTRATED — including when it could not be measured. A comparison that cannot prove its controls is not a weak finding, it is not a finding."
                            },
                            "score_delta": {
                              "type": "number",
                              "description": "PRESENT ONLY when `delta_attributable`. Absent means the pair supports no delta — read `delta_withheld_reason`, NOT \"no change\"."
                            },
                            "submitted_score_delta": {
                              "type": "number",
                              "description": "How much the caller’s OWN copy moved, on [0,1] — the number an A/B is asking for. Derived from the improvement report rather than `overall_score`, so it means the same thing on both sides of a version boundary. Held to the same noise floor."
                            },
                            "submitted_score_15_delta": {
                              "type": "number",
                              "description": "The same movement on the [1,5] axis every human-facing score is stated on."
                            },
                            "delta_withheld_reason": {
                              "type": "string",
                              "enum": [
                                "not_scored",
                                "evidence_not_controlled",
                                "artifact_type_mismatch",
                                "stop_reason_mismatch",
                                "inside_noise_floor",
                                "eval_version_boundary"
                              ],
                              "description": "Why no delta shipped. Typed because the causes need DIFFERENT things from the reader and most are not fixed by pinning evidence — see `remedy`, which is keyed to this value."
                            },
                            "noise_floor": {
                              "type": "number",
                              "description": "The floor |delta| had to clear, present whether or not it cleared — so a caller can see how close it came."
                            },
                            "version_boundary": {
                              "type": "object",
                              "description": "The eval_version transitions this pair straddles, with each one’s `kind`. Present whenever the two runs carry different versions. `recorded: false` means the ledger has no entry for one of them — \"cannot say\", not \"nothing crossed\"."
                            },
                            "caveat": {
                              "type": "string",
                              "description": "Plain-English statement of what this comparison does and does not support."
                            },
                            "remedy": {
                              "type": "string",
                              "description": "How to get a reportable delta out of these two runs. Present exactly when `delta_withheld_reason` is."
                            }
                          },
                          "required": [
                            "a",
                            "b",
                            "evidence_overlap",
                            "delta_attributable",
                            "caveat"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "comparison"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/gate": {
      "get": {
        "operationId": "evalRunGate",
        "summary": "Get Eval Run Gate",
        "description": "Fetch the machine verdict on the copy the caller SUBMITTED: passed, checks_passed/checks_total, score_15 against its threshold, and which failed. Use when wiring an eval into a pipeline as a send/hold decision — never gate on overall_score or lift, which follow the rewrite. Pass wait_ms (max 30000) to block until the run settles. gate is null while running or when the run refused (not_applicable_reason says why); a refusal is not a fail.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait_ms",
            "in": "query",
            "required": false,
            "description": "Optional long-poll budget in ms, hard-capped at 30000. Blocks until the run reaches complete / failed / canceled, then returns the same body an immediate poll would.",
            "schema": {
              "type": "integer",
              "description": "Optional long-poll budget in ms, hard-capped at 30000. Blocks until the run reaches complete / failed / canceled, then returns the same body an immediate poll would."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "run_id": {
                          "type": "string"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "eval_version": {
                          "type": "string",
                          "description": "The eval version this run was graded at. Gate thresholds are only comparable within one version — see the eval version ledger."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The run status, at the ROOT of the body — unlike GET /eval-runs/{id}, which nests it under `run`. The terminal success value is `complete` — never `completed`."
                        },
                        "gate": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "The machine verdict on the copy the caller SUBMITTED. NULL means this run has no submitted-side grade to gate on — still running, refused (see `not_applicable_reason`), or a grader mix that produced none. Never treat null as a fail: `passed: false` is a verdict on the copy and a refusal is emphatically not one.",
                          "properties": {
                            "passed": {
                              "type": [
                                "boolean",
                                "null"
                              ],
                              "description": "Did the submitted copy clear the pass bar."
                            },
                            "checks_passed": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "checks_total": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "denominator": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "enum": [
                                "all_dimensions",
                                "applicable_only",
                                null
                              ],
                              "description": "What `checks_total` counted. `applicable_only` (eval 2.33.0 and later, where the workspace has the flag on) means a rubric line this KIND of artifact could not satisfy left BOTH the numerator and the denominator, so the fraction is over the checks the copy could actually have met. `all_dimensions` counts every line, which is what every row before 2.33.0 means. ⚠️ Read this BEFORE pooling `score_15` across runs, and do NOT infer it from `eval_version`: the behaviour is per-workspace, so two runs stamped 2.33.0 can have been divided differently. Null on a run graded before the field existed — read that as `all_dimensions`, which is what it was."
                            },
                            "score_15": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "description": "The submitted side’s 1-5 score, `1 + 4 * checks_passed/checks_total`. Derived from binary per-line verdicts, so it is a fraction rendered on a five-point dial, not a rating."
                            },
                            "threshold": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "description": "The 1-5 bar `passed` was decided against. Null on runs graded before the bar was stamped — the stored bar there belongs to the IMPROVED side and must not be republished beside the submitted fraction."
                            },
                            "basis": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "enum": [
                                "prompt",
                                "message",
                                null
                              ],
                              "description": "Which submitted artifact the fraction describes."
                            },
                            "simulated": {
                              "type": "boolean",
                              "description": "True when the graded \"submitted\" side is a specimen the eval WROTE (a prompt-only run). A pipeline gating sends must know the fraction describes a simulation."
                            },
                            "dimensions_failed": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Rubric dimensions the submitted side failed, by FULL name. Each entry is the line’s whole text rather than a label, so it reads on its own beside `reasoning`. EXCLUDES lines the caller’s declared `artifact_type` marks not applicable, so it can be shorter than `checks_total - checks_passed`, which still counts every line. The report read names the SAME lines by STEM: `report.findings.failed[].dimension` on GET /eval-runs/{id}/report is the clause before the first colon, because there it renders as a bold lead-in to that line’s `reasoning`. Same lines, two renderings, on purpose — a diff between the two strings is expected, not a bug. This field is also UNCAPPED, where `failed[]` cuts at 8 and says so via `truncated`, so on a tenant-authored eval with a long rubric the two can differ in length as well."
                            },
                            "reasoning": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The judge’s rationale for the submitted side, verbatim; null when the run recorded none. `dimensions_failed` says WHICH lines failed and this says WHY, so a pipeline gating a send can report something a human can act on rather than a bare count."
                            },
                            "critique": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "What would have to change for the submitted side to pass, in the judge’s own words. Null on a FULL run rather than absent: a full run’s critique is written against the improved side, and publishing it beside the submitted fraction would be the same mistake `threshold` is null there to avoid. Read the null as “not measured on this run”, never as “nothing to say”."
                            }
                          },
                          "required": [
                            "passed",
                            "simulated",
                            "dimensions_failed"
                          ]
                        },
                        "not_applicable_reason": {
                          "type": "string",
                          "description": "Present exactly when the run refused to grade, saying why. A refusal is not a fail."
                        },
                        "error_message": {
                          "type": "string",
                          "description": "Present only on a failed run."
                        },
                        "regrade": {
                          "type": "object",
                          "description": "Present exactly when this run’s evidence pool is pinnable: the parameter set that holds it fixed for the next call, so a held draft’s edit is graded against the same quotes. Absent otherwise, never partial."
                        }
                      },
                      "required": [
                        "run_id",
                        "status",
                        "gate"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/report": {
      "get": {
        "operationId": "evalRunReport",
        "summary": "Get Eval Run Report",
        "description": "Fetch the canonical report card for one eval run as ready-to-paste markdown: your draft score vs the improved one, the bar, the transition, cited customer quotes, and any confidence caveat. Read when presenting a result to a person — paste the markdown as written rather than summarising it, so the numbers reported are the ones Amdahl computed.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The run status, mirrored at the root so `data.status` resolves here as it does on every other eval read. Identical to `report.status`. The terminal success value is `complete` — never `completed`."
                        },
                        "report": {
                          "type": "object",
                          "description": "The canonical report card. `markdown` is a string on every run state; `headline` and `findings` are null until the run reaches `complete`.",
                          "properties": {
                            "run_id": {
                              "type": "string"
                            },
                            "eval_slug": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "markdown": {
                              "type": "string"
                            },
                            "headline": {
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "findings": {
                              "type": [
                                "object",
                                "null"
                              ],
                              "description": "What did not hold up on the submitted copy: `failed[]` (one entry per rubric line missed, each `{dimension, reasoning}`), `contradicting[]`, and `truncated`. `dimension` is the rubric line’s STEM — the clause before the first colon — because the card renders it as a bold lead-in to that line’s `reasoning`, which carries the substance. The gate read names the SAME lines IN FULL: `gate.dimensions_failed` on GET /eval-runs/{id}/gate spells out each line’s whole text, because it travels without a reasoning field and the stem alone would drop the criterion. Same lines, two renderings, on purpose — a diff between the two strings is expected, not a bug. The two can also differ in LENGTH: `failed[]` cuts at 8 and says so via `truncated`, while `gate.dimensions_failed` is uncapped. On the shipped five-line rubric that cut never binds; a tenant-authored eval with a longer rubric can reach it."
                            }
                          },
                          "required": [
                            "run_id",
                            "eval_slug",
                            "status",
                            "markdown"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "report",
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/evidence": {
      "get": {
        "operationId": "evalRunEvidence",
        "summary": "Get Eval Run Evidence",
        "description": "Fetch the frozen customer-quote pool one eval run graded against: every quote with its id, tier, provenance and whether it reached the graded prompt, plus when the pool was frozen. Read when drafting an edit to re-grade against the SAME evidence (then pass evidence_from_run on the next run so the score delta is the edit, not a retrieval change), or when auditing what a verdict was scored on. evidence is null when the run never recorded a pool.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "run_id": {
                          "type": "string"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The run status, at the root as on every eval read. The terminal success value is `complete` — never `completed`."
                        },
                        "evidence": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "The frozen quote pool this run was graded against. Null means no pool was recorded (the run predates evidence recording, or retrieval never froze a set) — a fact, not an error, and not pinnable."
                        },
                        "regrade": {
                          "type": "object",
                          "description": "The pasteable `evidence_from_run` params for re-grading an edit against this same pool. Present exactly when the pool is pinnable on a settled run; absent otherwise."
                        }
                      },
                      "required": [
                        "run_id",
                        "eval_slug",
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/drafts": {
      "get": {
        "operationId": "evalRunDrafts",
        "summary": "Get Eval Run Drafts",
        "description": "Fetch both graded artifacts of one eval run side by side: the prompt and message you submitted, the improved versions the eval wrote, each with its score, checks fraction and per-rubric-line reasoning. Read when comparing your draft against the rewrite line by line — this is the only read that carries the texts themselves. Cited quotes stay on the evidence read.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "run_id": {
                          "type": "string"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "eval_version": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ],
                          "description": "The run status, at the root as on every eval read. The terminal success value is `complete` — never `completed`."
                        },
                        "submitted": {
                          "type": "object",
                          "description": "The prompt and message you sent, each with its score and per-line verdicts."
                        },
                        "improved": {
                          "type": "object",
                          "description": "The rewritten versions. `prompt` / `message` are null with an `absent_reason` on a run that correctly wrote no rewrite — never an empty string, never a zero score."
                        }
                      },
                      "required": [
                        "run_id",
                        "eval_slug",
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/eval-runs/{id}/improvement": {
      "get": {
        "operationId": "evalRunImprovement",
        "summary": "Get Eval Run Improvement Report",
        "description": "Fetch the before/after improvement report of one eval run in a bounded shape: the per-facet graded pair with scores, per-rubric-line verdicts, cited quotes and the not-applicable counters, plus lift, transition, suggestions and confidence. Read when the full run payload is too large for your transport and you need the facets — no other narrow read carries them.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "run_id": {
                          "type": "string"
                        },
                        "eval_slug": {
                          "type": "string"
                        },
                        "eval_version": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "complete",
                            "failed",
                            "canceled"
                          ]
                        },
                        "improvement": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "The before/after report. `facets[]` is the per-facet graded pair; each side carries score_15, checks_passed / checks_total, dimensions, quotes and the not-applicable counters. NULL — never an empty object, and never an empty `facets` — when the run produced no report (mode \"gate\", or any refusal); read `absent_reason` beside it."
                        },
                        "omitted": {
                          "type": "array",
                          "description": "The fields this bounded shape leaves on the full-row read, each with why and where. Present on EVERY response, so the omission is readable rather than inferred from a payload that came back smaller than expected.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "field": {
                                "type": "string"
                              },
                              "why": {
                                "type": "string"
                              },
                              "read": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "field",
                              "why",
                              "read"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "absent_reason": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Present only when `improvement` is null: why the run produced no report."
                        }
                      },
                      "required": [
                        "run_id",
                        "status",
                        "improvement",
                        "omitted"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/grader-kinds": {
      "get": {
        "operationId": "graderKindList",
        "summary": "List Grader Kinds",
        "description": "List every grader kind an eval can use: deterministic (rule checks, no LLM), sor_anchored (compare a figure to a ground-truth warehouse count), and judge (LLM scores a rubric). Use when authoring or explaining an eval. Returns id, name, description, and whether the kind makes an LLM call.",
        "tags": [
          "observability"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    },
    "/api/platform/v1/grader-kinds/{id}": {
      "get": {
        "operationId": "graderKindGet",
        "summary": "Get Grader Kind",
        "description": "Fetch one grader kind by id (deterministic / sor_anchored / judge). Use when rendering a single grader-kind detail card. Returns its name, description, and llm-usage flag, or null for an unknown id.",
        "tags": [
          "observability"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input - failed schema validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - missing scope or role",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "evals:read"
            ]
          },
          {
            "BearerAuth": [
              "evals:read"
            ]
          }
        ],
        "x-scopes": [
          "evals:read"
        ],
        "x-stability": "beta"
      }
    }
  },
  "webhooks": {}
}