HooshyarDocs

Admin API

Read and change the gateway configuration from a script or a pipeline. Every operation needs an admin token with the correct role and scope.

Base address

https://console.example.com/api/v1

Download the OpenAPI document /openapi.json

Authentication

Send an admin token in the Authorization: Bearer header. An owner makes tokens in the console.

bash
curl https://console.example.com/api/v1/auth/whoami \
  -H "Authorization: Bearer ${HOOSHYAR_TOKEN}"

Rules for writes

  • A write to a versioned resource needs the If-Match header. Send the version that you read. If the version changed, the answer is 412 and nothing changes.
  • Some writes need an Idempotency-Key header. Use a new UUID for each request. Use the same key again only to retry the same request.
  • Every operation can answer 429. Wait for the number of seconds in Retry-After, then send again.

Operations

GET /api/v1/auth/whoami

auth.whoami

Describe the calling principal and the operations it is allowed to call.

Role
member
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "principal": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "user"
            },
            "id": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "role": {
              "type": "string",
              "enum": [
                "member",
                "viewer",
                "admin",
                "owner"
              ]
            }
          },
          "required": [
            "kind",
            "id",
            "email",
            "role"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "token"
            },
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "tokenPrefix": {
              "type": "string"
            },
            "role": {
              "type": "string",
              "enum": [
                "member",
                "viewer",
                "admin",
                "owner"
              ]
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "kind",
            "id",
            "name",
            "tokenPrefix",
            "role",
            "scopes",
            "expiresAt"
          ],
          "additionalProperties": false
        }
      ]
    },
    "allowedOperations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "principal",
    "allowedOperations"
  ],
  "additionalProperties": false
}

GET /api/v1/tokens

tokens.list

List automation tokens (metadata only — never the secret or hash).

Role
owner
Scope
tokens:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tokenPrefix": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "member",
              "viewer",
              "admin",
              "owner"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "tokenPrefix",
          "role",
          "scopes",
          "createdByUserId",
          "createdAt",
          "expiresAt",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "tokens"
  ],
  "additionalProperties": false
}

POST /api/v1/tokens

tokens.mint

Mint an automation token; the plaintext secret is returned ONCE and never again.

Role
owner
Scope
tokens:write
Idempotency key
required
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "role": {
      "type": "string",
      "enum": [
        "viewer",
        "admin",
        "owner"
      ]
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "config:read",
          "config:write",
          "config:apply",
          "keys:read",
          "keys:write",
          "tokens:read",
          "tokens:write",
          "users:read",
          "users:write",
          "providers:read",
          "providers:write",
          "alerts:read",
          "alerts:write",
          "usage:read",
          "reports:write",
          "audit:read",
          "logs:read",
          "guardrails:activity:read",
          "guardrails:read",
          "guardrails:test",
          "retention:read",
          "subscription_lane:read",
          "tools:read",
          "connections:read",
          "packs:read",
          "skills:read"
        ]
      }
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "name",
    "role"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "token": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "tokenPrefix": {
          "type": "string"
        },
        "role": {
          "type": "string",
          "enum": [
            "member",
            "viewer",
            "admin",
            "owner"
          ]
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "lastUsedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "revokedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "secret": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "tokenPrefix",
        "role",
        "scopes",
        "createdByUserId",
        "createdAt",
        "expiresAt",
        "lastUsedAt",
        "revokedAt",
        "secret"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "token"
  ],
  "additionalProperties": false
}

DELETE /api/v1/tokens/{id}

tokens.revoke

Revoke an automation token (idempotent — it stops authenticating immediately).

Role
owner
Scope
tokens:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/config

config.read

Read the routing config as a declarative, round-trippable document.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "document": {
      "type": "object",
      "properties": {
        "schemaVersion": {
          "type": "number",
          "const": 1
        },
        "defaultRoute": {
          "type": "string"
        },
        "classifier": {
          "type": "object",
          "properties": {
            "confidenceThreshold": {
              "type": "number"
            },
            "semanticEnabled": {
              "type": "boolean"
            },
            "encoder": {
              "type": "string"
            },
            "llmFallbackEnabled": {
              "type": "boolean"
            },
            "llmFallbackModel": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "confidenceThreshold",
            "semanticEnabled",
            "encoder",
            "llmFallbackEnabled",
            "llmFallbackModel"
          ],
          "additionalProperties": false
        },
        "routes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "model": {
                "type": "string"
              },
              "fallbacks": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "params": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              "enabled": {
                "type": "boolean"
              },
              "requireZdr": {
                "default": false,
                "type": "boolean"
              },
              "packBudgetTokens": {
                "default": null,
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "utterances": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "name",
              "model",
              "fallbacks",
              "params",
              "enabled",
              "requireZdr",
              "packBudgetTokens",
              "utterances"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "schemaVersion",
        "defaultRoute",
        "classifier",
        "routes"
      ],
      "additionalProperties": false
    },
    "version": {
      "type": "number"
    },
    "hash": {
      "type": "string"
    }
  },
  "required": [
    "document",
    "version",
    "hash"
  ],
  "additionalProperties": false
}

PUT /api/v1/config

config.apply

Apply a whole config document declaratively — routes absent from it are deleted.

Role
admin
Scope
config:apply
Needs If-Match
✓
Idempotency key
required
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "number",
      "const": 1
    },
    "defaultRoute": {
      "type": "string"
    },
    "classifier": {
      "type": "object",
      "properties": {
        "confidenceThreshold": {
          "type": "number"
        },
        "semanticEnabled": {
          "type": "boolean"
        },
        "encoder": {
          "type": "string"
        },
        "llmFallbackEnabled": {
          "type": "boolean"
        },
        "llmFallbackModel": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "confidenceThreshold",
        "semanticEnabled",
        "encoder",
        "llmFallbackEnabled",
        "llmFallbackModel"
      ]
    },
    "routes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "fallbacks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "params": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "enabled": {
            "type": "boolean"
          },
          "requireZdr": {
            "default": false,
            "type": "boolean"
          },
          "packBudgetTokens": {
            "default": null,
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "utterances": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "model",
          "fallbacks",
          "params",
          "enabled",
          "utterances"
        ]
      }
    }
  },
  "required": [
    "schemaVersion",
    "defaultRoute",
    "classifier",
    "routes"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "applied": {
      "type": "boolean"
    },
    "version": {
      "type": "number"
    },
    "diff": {
      "type": "object",
      "properties": {
        "routes": {
          "type": "object",
          "properties": {
            "added": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "removed": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "changed": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "field": {
                          "type": "string"
                        },
                        "from": {},
                        "to": {}
                      },
                      "required": [
                        "field",
                        "from",
                        "to"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "utterances": {
                    "type": "object",
                    "properties": {
                      "added": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "removed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "added",
                      "removed"
                    ],
                    "additionalProperties": false
                  },
                  "utterancesReordered": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "fields",
                  "utterances",
                  "utterancesReordered"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "added",
            "removed",
            "changed"
          ],
          "additionalProperties": false
        },
        "defaultRoute": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "from": {},
                "to": {}
              },
              "required": [
                "field",
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "classifier": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string"
              },
              "from": {},
              "to": {}
            },
            "required": [
              "field",
              "from",
              "to"
            ],
            "additionalProperties": false
          }
        },
        "empty": {
          "type": "boolean"
        }
      },
      "required": [
        "routes",
        "defaultRoute",
        "classifier",
        "empty"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "applied",
    "version",
    "diff"
  ],
  "additionalProperties": false
}

POST /api/v1/config/validate

config.validate

Dry-run a config document: diagnostics plus a structured diff against the live config.

Role
viewer
Scope
config:read
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "number",
      "const": 1
    },
    "defaultRoute": {
      "type": "string"
    },
    "classifier": {
      "type": "object",
      "properties": {
        "confidenceThreshold": {
          "type": "number"
        },
        "semanticEnabled": {
          "type": "boolean"
        },
        "encoder": {
          "type": "string"
        },
        "llmFallbackEnabled": {
          "type": "boolean"
        },
        "llmFallbackModel": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "confidenceThreshold",
        "semanticEnabled",
        "encoder",
        "llmFallbackEnabled",
        "llmFallbackModel"
      ]
    },
    "routes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "fallbacks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "params": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "enabled": {
            "type": "boolean"
          },
          "requireZdr": {
            "default": false,
            "type": "boolean"
          },
          "packBudgetTokens": {
            "default": null,
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "utterances": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "model",
          "fallbacks",
          "params",
          "enabled",
          "utterances"
        ]
      }
    }
  },
  "required": [
    "schemaVersion",
    "defaultRoute",
    "classifier",
    "routes"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean"
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ]
          },
          "code": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "severity",
          "code",
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "diff": {
      "type": "object",
      "properties": {
        "routes": {
          "type": "object",
          "properties": {
            "added": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "removed": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "changed": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "field": {
                          "type": "string"
                        },
                        "from": {},
                        "to": {}
                      },
                      "required": [
                        "field",
                        "from",
                        "to"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "utterances": {
                    "type": "object",
                    "properties": {
                      "added": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "removed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "added",
                      "removed"
                    ],
                    "additionalProperties": false
                  },
                  "utterancesReordered": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "fields",
                  "utterances",
                  "utterancesReordered"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "added",
            "removed",
            "changed"
          ],
          "additionalProperties": false
        },
        "defaultRoute": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "from": {},
                "to": {}
              },
              "required": [
                "field",
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "classifier": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string"
              },
              "from": {},
              "to": {}
            },
            "required": [
              "field",
              "from",
              "to"
            ],
            "additionalProperties": false
          }
        },
        "empty": {
          "type": "boolean"
        }
      },
      "required": [
        "routes",
        "defaultRoute",
        "classifier",
        "empty"
      ],
      "additionalProperties": false
    },
    "baseVersion": {
      "type": "number"
    },
    "documentHash": {
      "type": "string"
    },
    "catalogChecked": {
      "type": "boolean"
    }
  },
  "required": [
    "valid",
    "diagnostics",
    "diff",
    "baseVersion",
    "documentHash",
    "catalogChecked"
  ],
  "additionalProperties": false
}

GET /api/v1/config/generations

config.generations.list

List the routing-config history, newest first: one entry per change to the document.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "generations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "version": {
            "type": "number"
          },
          "hash": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "baseline",
              "route.upsert",
              "route.delete",
              "utterances.replace",
              "settings.update",
              "config.apply"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "routeCount": {
            "type": "number"
          }
        },
        "required": [
          "version",
          "hash",
          "source",
          "createdAt",
          "routeCount"
        ],
        "additionalProperties": false
      }
    },
    "next": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "required": [
    "generations",
    "next"
  ],
  "additionalProperties": false
}

GET /api/v1/config/generations/{version}

config.generations.read

Read one past routing-config state as a document, ready to validate and apply back.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number"
    },
    "hash": {
      "type": "string"
    },
    "source": {
      "type": "string",
      "enum": [
        "baseline",
        "route.upsert",
        "route.delete",
        "utterances.replace",
        "settings.update",
        "config.apply"
      ]
    },
    "createdAt": {
      "type": "string"
    },
    "routeCount": {
      "type": "number"
    },
    "document": {
      "type": "object",
      "properties": {
        "schemaVersion": {
          "type": "number",
          "const": 1
        },
        "defaultRoute": {
          "type": "string"
        },
        "classifier": {
          "type": "object",
          "properties": {
            "confidenceThreshold": {
              "type": "number"
            },
            "semanticEnabled": {
              "type": "boolean"
            },
            "encoder": {
              "type": "string"
            },
            "llmFallbackEnabled": {
              "type": "boolean"
            },
            "llmFallbackModel": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "confidenceThreshold",
            "semanticEnabled",
            "encoder",
            "llmFallbackEnabled",
            "llmFallbackModel"
          ],
          "additionalProperties": false
        },
        "routes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "model": {
                "type": "string"
              },
              "fallbacks": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "params": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              "enabled": {
                "type": "boolean"
              },
              "requireZdr": {
                "default": false,
                "type": "boolean"
              },
              "packBudgetTokens": {
                "default": null,
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "utterances": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "name",
              "model",
              "fallbacks",
              "params",
              "enabled",
              "requireZdr",
              "packBudgetTokens",
              "utterances"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "schemaVersion",
        "defaultRoute",
        "classifier",
        "routes"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "version",
    "hash",
    "source",
    "createdAt",
    "routeCount",
    "document"
  ],
  "additionalProperties": false
}

PUT /api/v1/config/routes/{name}

config.route.upsert

Create or update one route (model, fallbacks, params, enabled).

Role
admin
Scope
config:write
Needs If-Match
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1
    },
    "fallbacks": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "params": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "enabled": {
      "default": true,
      "type": "boolean"
    },
    "requireZdr": {
      "default": false,
      "type": "boolean"
    },
    "packBudgetTokens": {
      "default": null,
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "model"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "created": {
      "type": "boolean"
    }
  },
  "required": [
    "ok",
    "created"
  ],
  "additionalProperties": false
}

DELETE /api/v1/config/routes/{name}

config.route.delete

Delete one route and its utterance examples.

Role
admin
Scope
config:write
Needs If-Match
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/config/settings

config.settings.update

Update the default route and/or the classifier settings.

Role
admin
Scope
config:write
Needs If-Match
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "defaultRoute": {
      "type": "string",
      "minLength": 1
    },
    "classifier": {
      "type": "object",
      "properties": {
        "confidenceThreshold": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "semanticEnabled": {
          "type": "boolean"
        },
        "llmFallbackEnabled": {
          "type": "boolean"
        }
      }
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/models

models.list

List the chassis model catalog — the valid targets for a route.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "models": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "models"
  ],
  "additionalProperties": false
}

GET /api/v1/usage

usage.report

Aggregate request usage grouped by one dimension over an optional date range.

Role
member
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groupBy": {
      "type": "string",
      "enum": [
        "route",
        "model",
        "user",
        "tag",
        "key",
        "channel",
        "client",
        "session",
        "subject"
      ]
    },
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "promptTokens": {
            "type": "number"
          },
          "completionTokens": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          },
          "p95LatencyMs": {
            "type": "number"
          },
          "avgTtftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedRequests": {
            "type": "number"
          },
          "subscriptionRequests": {
            "type": "number"
          },
          "imageCount": {
            "type": "number"
          },
          "audioSeconds": {
            "type": "number"
          },
          "characters": {
            "type": "number"
          },
          "documents": {
            "type": "number"
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "group",
          "requests",
          "promptTokens",
          "completionTokens",
          "totalTokens",
          "cachedTokens",
          "avgLatencyMs",
          "p95LatencyMs",
          "avgTtftMs",
          "costUsd",
          "unpricedRequests",
          "subscriptionRequests",
          "imageCount",
          "audioSeconds",
          "characters",
          "documents",
          "subjectName"
        ],
        "additionalProperties": false
      }
    },
    "truncated": {
      "type": "boolean"
    }
  },
  "required": [
    "groupBy",
    "from",
    "to",
    "rows",
    "truncated"
  ],
  "additionalProperties": false
}

POST /api/v1/reports/run

reports.run

Run one report (a built-in or saved report by id, or a draft spec) for the caller.

Role
member
Scope
usage:read
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "spec": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "requests",
            "tool_calls",
            "agent_metrics",
            "outcomes"
          ]
        },
        "dimensions": {
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "client",
              "model",
              "route",
              "subject",
              "key",
              "channel",
              "tag",
              "session",
              "server",
              "tool",
              "repository",
              "day",
              "week",
              "month"
            ]
          }
        },
        "measures": {
          "minItems": 1,
          "maxItems": 40,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "requests",
              "input_tokens",
              "output_tokens",
              "total_tokens",
              "cached_tokens",
              "cost_usd",
              "unpriced_requests",
              "users",
              "sessions",
              "active_hours",
              "latency_avg_ms",
              "latency_p95_ms",
              "ttft_avg_ms",
              "cost_share",
              "request_share",
              "cost_per_user",
              "requests_per_user",
              "cost_per_1k_requests",
              "tokens_per_request",
              "cost_per_1m_tokens",
              "cost_per_1k_sessions",
              "cost_per_active_hour",
              "cache_hit_rate",
              "cost_decomposition",
              "calls",
              "ok",
              "failed",
              "unknown",
              "denied",
              "pending",
              "unpriced_calls",
              "cost_per_ok_call",
              "operations",
              "estimated_cost_usd",
              "merged_prs",
              "reverted_prs",
              "revert_rate",
              "reviews",
              "joined_prs",
              "cost_per_merged_pr"
            ]
          }
        },
        "filters": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "enum": [
              "client",
              "model",
              "route",
              "subject",
              "key",
              "channel",
              "tag",
              "session",
              "server",
              "tool",
              "repository",
              "day",
              "week",
              "month"
            ]
          },
          "additionalProperties": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        },
        "range": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "7d",
                "30d",
                "mtd",
                "last_month"
              ]
            },
            {
              "type": "object",
              "properties": {
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ]
            }
          ]
        },
        "compare": {
          "type": "string",
          "enum": [
            "none",
            "previous_period"
          ]
        },
        "view": {
          "type": "string",
          "enum": [
            "table",
            "bar",
            "line",
            "stacked",
            "waterfall"
          ]
        }
      },
      "required": [
        "source",
        "dimensions",
        "measures",
        "filters",
        "range",
        "compare",
        "view"
      ]
    },
    "limit": {
      "default": 500,
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "result": {
      "type": "object",
      "properties": {
        "spec": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "requests",
                "tool_calls",
                "agent_metrics",
                "outcomes"
              ]
            },
            "dimensions": {
              "maxItems": 2,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              }
            },
            "measures": {
              "minItems": 1,
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "requests",
                  "input_tokens",
                  "output_tokens",
                  "total_tokens",
                  "cached_tokens",
                  "cost_usd",
                  "unpriced_requests",
                  "users",
                  "sessions",
                  "active_hours",
                  "latency_avg_ms",
                  "latency_p95_ms",
                  "ttft_avg_ms",
                  "cost_share",
                  "request_share",
                  "cost_per_user",
                  "requests_per_user",
                  "cost_per_1k_requests",
                  "tokens_per_request",
                  "cost_per_1m_tokens",
                  "cost_per_1k_sessions",
                  "cost_per_active_hour",
                  "cache_hit_rate",
                  "cost_decomposition",
                  "calls",
                  "ok",
                  "failed",
                  "unknown",
                  "denied",
                  "pending",
                  "unpriced_calls",
                  "cost_per_ok_call",
                  "operations",
                  "estimated_cost_usd",
                  "merged_prs",
                  "reverted_prs",
                  "revert_rate",
                  "reviews",
                  "joined_prs",
                  "cost_per_merged_pr"
                ]
              }
            },
            "filters": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              },
              "additionalProperties": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            },
            "range": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "7d",
                    "30d",
                    "mtd",
                    "last_month"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "compare": {
              "type": "string",
              "enum": [
                "none",
                "previous_period"
              ]
            },
            "view": {
              "type": "string",
              "enum": [
                "table",
                "bar",
                "line",
                "stacked",
                "waterfall"
              ]
            }
          },
          "required": [
            "source",
            "dimensions",
            "measures",
            "filters",
            "range",
            "compare",
            "view"
          ],
          "additionalProperties": false
        },
        "window": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "string",
                "null"
              ]
            },
            "to": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ],
          "additionalProperties": false
        },
        "previousWindow": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "groups": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "current": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "previous": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "delta": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "floor": {
                "type": "boolean"
              },
              "previousFloor": {
                "type": "boolean"
              }
            },
            "required": [
              "groups",
              "current",
              "previous",
              "delta",
              "floor",
              "previousFloor"
            ],
            "additionalProperties": false
          }
        },
        "total": {
          "type": "object",
          "properties": {
            "groups": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "current": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "previous": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "delta": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "floor": {
              "type": "boolean"
            },
            "previousFloor": {
              "type": "boolean"
            }
          },
          "required": [
            "groups",
            "current",
            "previous",
            "delta",
            "floor",
            "previousFloor"
          ],
          "additionalProperties": false
        },
        "decomposition": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "previousUsd": {
                  "type": "number"
                },
                "currentUsd": {
                  "type": "number"
                },
                "deltaUsd": {
                  "type": "number"
                },
                "parts": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "number"
                    },
                    "requestsPerUser": {
                      "type": "number"
                    },
                    "inputTokensPerRequest": {
                      "type": "number"
                    },
                    "outputTokensPerRequest": {
                      "type": "number"
                    },
                    "pricePerToken": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "users",
                    "requestsPerUser",
                    "inputTokensPerRequest",
                    "outputTokensPerRequest",
                    "pricePerToken"
                  ],
                  "additionalProperties": false
                },
                "unmodelledUsd": {
                  "type": "number"
                },
                "floor": {
                  "type": "boolean"
                }
              },
              "required": [
                "previousUsd",
                "currentUsd",
                "deltaUsd",
                "parts",
                "unmodelledUsd",
                "floor"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "coverage": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "dimensionsSince": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "rowsBefore": {
                  "type": "number"
                },
                "previousRowsBefore": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "dimensionsSince",
                "rowsBefore",
                "previousRowsBefore"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "spec",
        "window",
        "previousWindow",
        "rows",
        "total",
        "decomposition",
        "coverage"
      ],
      "additionalProperties": false
    },
    "rowCount": {
      "type": "number"
    },
    "truncated": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "title",
    "result",
    "rowCount",
    "truncated"
  ],
  "additionalProperties": false
}

GET /api/v1/reports

reports.list

List the reports the caller may open: built-in, their own, and shared with their role.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "builtIn": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "built_in",
              "saved"
            ]
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "requests",
                  "tool_calls",
                  "agent_metrics",
                  "outcomes"
                ]
              },
              "dimensions": {
                "maxItems": 2,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                }
              },
              "measures": {
                "minItems": 1,
                "maxItems": 40,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "requests",
                    "input_tokens",
                    "output_tokens",
                    "total_tokens",
                    "cached_tokens",
                    "cost_usd",
                    "unpriced_requests",
                    "users",
                    "sessions",
                    "active_hours",
                    "latency_avg_ms",
                    "latency_p95_ms",
                    "ttft_avg_ms",
                    "cost_share",
                    "request_share",
                    "cost_per_user",
                    "requests_per_user",
                    "cost_per_1k_requests",
                    "tokens_per_request",
                    "cost_per_1m_tokens",
                    "cost_per_1k_sessions",
                    "cost_per_active_hour",
                    "cache_hit_rate",
                    "cost_decomposition",
                    "calls",
                    "ok",
                    "failed",
                    "unknown",
                    "denied",
                    "pending",
                    "unpriced_calls",
                    "cost_per_ok_call",
                    "operations",
                    "estimated_cost_usd",
                    "merged_prs",
                    "reverted_prs",
                    "revert_rate",
                    "reviews",
                    "joined_prs",
                    "cost_per_merged_pr"
                  ]
                }
              },
              "filters": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                },
                "additionalProperties": {
                  "maxItems": 50,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              },
              "range": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "7d",
                      "30d",
                      "mtd",
                      "last_month"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "from",
                      "to"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "compare": {
                "type": "string",
                "enum": [
                  "none",
                  "previous_period"
                ]
              },
              "view": {
                "type": "string",
                "enum": [
                  "table",
                  "bar",
                  "line",
                  "stacked",
                  "waterfall"
                ]
              }
            },
            "required": [
              "source",
              "dimensions",
              "measures",
              "filters",
              "range",
              "compare",
              "view"
            ],
            "additionalProperties": false
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "visibility": {
            "type": "string",
            "enum": [
              "private",
              "role:viewer",
              "role:admin",
              "role:owner"
            ]
          },
          "pinned": {
            "type": "boolean"
          },
          "editable": {
            "type": "boolean"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "title",
          "description",
          "spec",
          "ownerEmail",
          "visibility",
          "pinned",
          "editable",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    },
    "mine": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "built_in",
              "saved"
            ]
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "requests",
                  "tool_calls",
                  "agent_metrics",
                  "outcomes"
                ]
              },
              "dimensions": {
                "maxItems": 2,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                }
              },
              "measures": {
                "minItems": 1,
                "maxItems": 40,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "requests",
                    "input_tokens",
                    "output_tokens",
                    "total_tokens",
                    "cached_tokens",
                    "cost_usd",
                    "unpriced_requests",
                    "users",
                    "sessions",
                    "active_hours",
                    "latency_avg_ms",
                    "latency_p95_ms",
                    "ttft_avg_ms",
                    "cost_share",
                    "request_share",
                    "cost_per_user",
                    "requests_per_user",
                    "cost_per_1k_requests",
                    "tokens_per_request",
                    "cost_per_1m_tokens",
                    "cost_per_1k_sessions",
                    "cost_per_active_hour",
                    "cache_hit_rate",
                    "cost_decomposition",
                    "calls",
                    "ok",
                    "failed",
                    "unknown",
                    "denied",
                    "pending",
                    "unpriced_calls",
                    "cost_per_ok_call",
                    "operations",
                    "estimated_cost_usd",
                    "merged_prs",
                    "reverted_prs",
                    "revert_rate",
                    "reviews",
                    "joined_prs",
                    "cost_per_merged_pr"
                  ]
                }
              },
              "filters": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                },
                "additionalProperties": {
                  "maxItems": 50,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              },
              "range": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "7d",
                      "30d",
                      "mtd",
                      "last_month"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "from",
                      "to"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "compare": {
                "type": "string",
                "enum": [
                  "none",
                  "previous_period"
                ]
              },
              "view": {
                "type": "string",
                "enum": [
                  "table",
                  "bar",
                  "line",
                  "stacked",
                  "waterfall"
                ]
              }
            },
            "required": [
              "source",
              "dimensions",
              "measures",
              "filters",
              "range",
              "compare",
              "view"
            ],
            "additionalProperties": false
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "visibility": {
            "type": "string",
            "enum": [
              "private",
              "role:viewer",
              "role:admin",
              "role:owner"
            ]
          },
          "pinned": {
            "type": "boolean"
          },
          "editable": {
            "type": "boolean"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "title",
          "description",
          "spec",
          "ownerEmail",
          "visibility",
          "pinned",
          "editable",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    },
    "shared": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "built_in",
              "saved"
            ]
          },
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "requests",
                  "tool_calls",
                  "agent_metrics",
                  "outcomes"
                ]
              },
              "dimensions": {
                "maxItems": 2,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                }
              },
              "measures": {
                "minItems": 1,
                "maxItems": 40,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "requests",
                    "input_tokens",
                    "output_tokens",
                    "total_tokens",
                    "cached_tokens",
                    "cost_usd",
                    "unpriced_requests",
                    "users",
                    "sessions",
                    "active_hours",
                    "latency_avg_ms",
                    "latency_p95_ms",
                    "ttft_avg_ms",
                    "cost_share",
                    "request_share",
                    "cost_per_user",
                    "requests_per_user",
                    "cost_per_1k_requests",
                    "tokens_per_request",
                    "cost_per_1m_tokens",
                    "cost_per_1k_sessions",
                    "cost_per_active_hour",
                    "cache_hit_rate",
                    "cost_decomposition",
                    "calls",
                    "ok",
                    "failed",
                    "unknown",
                    "denied",
                    "pending",
                    "unpriced_calls",
                    "cost_per_ok_call",
                    "operations",
                    "estimated_cost_usd",
                    "merged_prs",
                    "reverted_prs",
                    "revert_rate",
                    "reviews",
                    "joined_prs",
                    "cost_per_merged_pr"
                  ]
                }
              },
              "filters": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "enum": [
                    "client",
                    "model",
                    "route",
                    "subject",
                    "key",
                    "channel",
                    "tag",
                    "session",
                    "server",
                    "tool",
                    "repository",
                    "day",
                    "week",
                    "month"
                  ]
                },
                "additionalProperties": {
                  "maxItems": 50,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              },
              "range": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "7d",
                      "30d",
                      "mtd",
                      "last_month"
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "from",
                      "to"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "compare": {
                "type": "string",
                "enum": [
                  "none",
                  "previous_period"
                ]
              },
              "view": {
                "type": "string",
                "enum": [
                  "table",
                  "bar",
                  "line",
                  "stacked",
                  "waterfall"
                ]
              }
            },
            "required": [
              "source",
              "dimensions",
              "measures",
              "filters",
              "range",
              "compare",
              "view"
            ],
            "additionalProperties": false
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "visibility": {
            "type": "string",
            "enum": [
              "private",
              "role:viewer",
              "role:admin",
              "role:owner"
            ]
          },
          "pinned": {
            "type": "boolean"
          },
          "editable": {
            "type": "boolean"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "title",
          "description",
          "spec",
          "ownerEmail",
          "visibility",
          "pinned",
          "editable",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "builtIn",
    "mine",
    "shared"
  ],
  "additionalProperties": false
}

POST /api/v1/reports

reports.save

Save a report for the caller: create one, or replace one they own. It stores the question, never the figures.

Role
viewer
Scope
reports:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "spec": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "requests",
            "tool_calls",
            "agent_metrics",
            "outcomes"
          ]
        },
        "dimensions": {
          "maxItems": 2,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "client",
              "model",
              "route",
              "subject",
              "key",
              "channel",
              "tag",
              "session",
              "server",
              "tool",
              "repository",
              "day",
              "week",
              "month"
            ]
          }
        },
        "measures": {
          "minItems": 1,
          "maxItems": 40,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "requests",
              "input_tokens",
              "output_tokens",
              "total_tokens",
              "cached_tokens",
              "cost_usd",
              "unpriced_requests",
              "users",
              "sessions",
              "active_hours",
              "latency_avg_ms",
              "latency_p95_ms",
              "ttft_avg_ms",
              "cost_share",
              "request_share",
              "cost_per_user",
              "requests_per_user",
              "cost_per_1k_requests",
              "tokens_per_request",
              "cost_per_1m_tokens",
              "cost_per_1k_sessions",
              "cost_per_active_hour",
              "cache_hit_rate",
              "cost_decomposition",
              "calls",
              "ok",
              "failed",
              "unknown",
              "denied",
              "pending",
              "unpriced_calls",
              "cost_per_ok_call",
              "operations",
              "estimated_cost_usd",
              "merged_prs",
              "reverted_prs",
              "revert_rate",
              "reviews",
              "joined_prs",
              "cost_per_merged_pr"
            ]
          }
        },
        "filters": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "enum": [
              "client",
              "model",
              "route",
              "subject",
              "key",
              "channel",
              "tag",
              "session",
              "server",
              "tool",
              "repository",
              "day",
              "week",
              "month"
            ]
          },
          "additionalProperties": {
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        },
        "range": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "7d",
                "30d",
                "mtd",
                "last_month"
              ]
            },
            {
              "type": "object",
              "properties": {
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ]
            }
          ]
        },
        "compare": {
          "type": "string",
          "enum": [
            "none",
            "previous_period"
          ]
        },
        "view": {
          "type": "string",
          "enum": [
            "table",
            "bar",
            "line",
            "stacked",
            "waterfall"
          ]
        }
      },
      "required": [
        "source",
        "dimensions",
        "measures",
        "filters",
        "range",
        "compare",
        "view"
      ]
    },
    "visibility": {
      "default": "private",
      "type": "string",
      "enum": [
        "private",
        "role:viewer",
        "role:admin",
        "role:owner"
      ]
    },
    "pinned": {
      "default": false,
      "type": "boolean"
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "title",
    "spec"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "report": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "built_in",
            "saved"
          ]
        },
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "spec": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "requests",
                "tool_calls",
                "agent_metrics",
                "outcomes"
              ]
            },
            "dimensions": {
              "maxItems": 2,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              }
            },
            "measures": {
              "minItems": 1,
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "requests",
                  "input_tokens",
                  "output_tokens",
                  "total_tokens",
                  "cached_tokens",
                  "cost_usd",
                  "unpriced_requests",
                  "users",
                  "sessions",
                  "active_hours",
                  "latency_avg_ms",
                  "latency_p95_ms",
                  "ttft_avg_ms",
                  "cost_share",
                  "request_share",
                  "cost_per_user",
                  "requests_per_user",
                  "cost_per_1k_requests",
                  "tokens_per_request",
                  "cost_per_1m_tokens",
                  "cost_per_1k_sessions",
                  "cost_per_active_hour",
                  "cache_hit_rate",
                  "cost_decomposition",
                  "calls",
                  "ok",
                  "failed",
                  "unknown",
                  "denied",
                  "pending",
                  "unpriced_calls",
                  "cost_per_ok_call",
                  "operations",
                  "estimated_cost_usd",
                  "merged_prs",
                  "reverted_prs",
                  "revert_rate",
                  "reviews",
                  "joined_prs",
                  "cost_per_merged_pr"
                ]
              }
            },
            "filters": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              },
              "additionalProperties": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            },
            "range": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "7d",
                    "30d",
                    "mtd",
                    "last_month"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "compare": {
              "type": "string",
              "enum": [
                "none",
                "previous_period"
              ]
            },
            "view": {
              "type": "string",
              "enum": [
                "table",
                "bar",
                "line",
                "stacked",
                "waterfall"
              ]
            }
          },
          "required": [
            "source",
            "dimensions",
            "measures",
            "filters",
            "range",
            "compare",
            "view"
          ],
          "additionalProperties": false
        },
        "ownerEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "visibility": {
          "type": "string",
          "enum": [
            "private",
            "role:viewer",
            "role:admin",
            "role:owner"
          ]
        },
        "pinned": {
          "type": "boolean"
        },
        "editable": {
          "type": "boolean"
        },
        "updatedAt": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "kind",
        "id",
        "title",
        "description",
        "spec",
        "ownerEmail",
        "visibility",
        "pinned",
        "editable",
        "updatedAt"
      ],
      "additionalProperties": false
    },
    "created": {
      "type": "boolean"
    }
  },
  "required": [
    "report",
    "created"
  ],
  "additionalProperties": false
}

GET /api/v1/usage/series

usage.series

Read usage per hour or day: requests, tokens, cost, and latency and time-to-first-token percentiles.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "bucket": {
      "type": "string",
      "enum": [
        "hour",
        "day"
      ]
    },
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "points": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bucket": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          },
          "p50LatencyMs": {
            "type": "number"
          },
          "p95LatencyMs": {
            "type": "number"
          },
          "p50TtftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "p95TtftMs": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "bucket",
          "requests",
          "totalTokens",
          "cachedTokens",
          "costUsd",
          "avgLatencyMs",
          "p50LatencyMs",
          "p95LatencyMs",
          "p50TtftMs",
          "p95TtftMs"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "bucket",
    "from",
    "to",
    "points"
  ],
  "additionalProperties": false
}

GET /api/v1/usage/spend-split

usage.spend-split

Read interactive and batch spend for one window, side by side. Only the money is added up.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "interactive": {
      "type": "object",
      "properties": {
        "requests": {
          "type": "number"
        },
        "totalTokens": {
          "type": "number"
        },
        "costUsd": {
          "type": "number"
        },
        "unpricedRequests": {
          "type": "number"
        }
      },
      "required": [
        "requests",
        "totalTokens",
        "costUsd",
        "unpricedRequests"
      ],
      "additionalProperties": false
    },
    "batch": {
      "type": "object",
      "properties": {
        "batches": {
          "type": "number"
        },
        "logicalRequests": {
          "type": "number"
        },
        "totalTokens": {
          "type": "number"
        },
        "costUsd": {
          "type": "number"
        },
        "unpricedRows": {
          "type": "number"
        }
      },
      "required": [
        "batches",
        "logicalRequests",
        "totalTokens",
        "costUsd",
        "unpricedRows"
      ],
      "additionalProperties": false
    },
    "byModel": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "batches": {
            "type": "number"
          },
          "logicalRequests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedRows": {
            "type": "number"
          }
        },
        "required": [
          "model",
          "batches",
          "logicalRequests",
          "totalTokens",
          "cachedTokens",
          "costUsd",
          "unpricedRows"
        ],
        "additionalProperties": false
      }
    },
    "combinedCostUsd": {
      "type": "number"
    },
    "caveat": {
      "type": "string"
    }
  },
  "required": [
    "interactive",
    "batch",
    "byModel",
    "combinedCostUsd",
    "caveat"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/executive

reports.executive

Read the executive summary: spend, traffic, latency, top routes and models, and credit alerts.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "cost": {
      "type": "object",
      "properties": {
        "usd": {
          "type": "number"
        },
        "unpricedRequests": {
          "type": "number"
        },
        "subscriptionRequests": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        }
      },
      "required": [
        "usd",
        "unpricedRequests",
        "subscriptionRequests",
        "requests"
      ],
      "additionalProperties": false
    },
    "requests": {
      "type": "number"
    },
    "totalTokens": {
      "type": "number"
    },
    "cachedTokens": {
      "type": "number"
    },
    "avgLatencyMs": {
      "type": "number"
    },
    "p95LatencyMs": {
      "type": "number"
    },
    "avgTtftMs": {
      "type": [
        "number",
        "null"
      ]
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bucket": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          },
          "p50LatencyMs": {
            "type": "number"
          },
          "p95LatencyMs": {
            "type": "number"
          },
          "p50TtftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "p95TtftMs": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "bucket",
          "requests",
          "totalTokens",
          "cachedTokens",
          "costUsd",
          "avgLatencyMs",
          "p50LatencyMs",
          "p95LatencyMs",
          "p50TtftMs",
          "p95TtftMs"
        ],
        "additionalProperties": false
      }
    },
    "topRoutes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "promptTokens": {
            "type": "number"
          },
          "completionTokens": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          },
          "p95LatencyMs": {
            "type": "number"
          },
          "avgTtftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedRequests": {
            "type": "number"
          },
          "subscriptionRequests": {
            "type": "number"
          },
          "imageCount": {
            "type": "number"
          },
          "audioSeconds": {
            "type": "number"
          },
          "characters": {
            "type": "number"
          },
          "documents": {
            "type": "number"
          }
        },
        "required": [
          "group",
          "requests",
          "promptTokens",
          "completionTokens",
          "totalTokens",
          "cachedTokens",
          "avgLatencyMs",
          "p95LatencyMs",
          "avgTtftMs",
          "costUsd",
          "unpricedRequests",
          "subscriptionRequests",
          "imageCount",
          "audioSeconds",
          "characters",
          "documents"
        ],
        "additionalProperties": false
      }
    },
    "topModels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "promptTokens": {
            "type": "number"
          },
          "completionTokens": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          },
          "p95LatencyMs": {
            "type": "number"
          },
          "avgTtftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedRequests": {
            "type": "number"
          },
          "subscriptionRequests": {
            "type": "number"
          },
          "imageCount": {
            "type": "number"
          },
          "audioSeconds": {
            "type": "number"
          },
          "characters": {
            "type": "number"
          },
          "documents": {
            "type": "number"
          }
        },
        "required": [
          "group",
          "requests",
          "promptTokens",
          "completionTokens",
          "totalTokens",
          "cachedTokens",
          "avgLatencyMs",
          "p95LatencyMs",
          "avgTtftMs",
          "costUsd",
          "unpricedRequests",
          "subscriptionRequests",
          "imageCount",
          "audioSeconds",
          "characters",
          "documents"
        ],
        "additionalProperties": false
      }
    },
    "activeKeys": {
      "type": "number"
    },
    "creditAlerts": {
      "type": "number"
    }
  },
  "required": [
    "from",
    "to",
    "cost",
    "requests",
    "totalTokens",
    "cachedTokens",
    "avgLatencyMs",
    "p95LatencyMs",
    "avgTtftMs",
    "series",
    "topRoutes",
    "topModels",
    "activeKeys",
    "creditAlerts"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/team

reports.team

Report usage per person, rolled up through key ownership, with an unassigned bucket.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "members": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "userId": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "member",
                  "viewer",
                  "admin",
                  "owner"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "keys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cachedTokens": {
            "type": "number"
          },
          "cost": {
            "type": "object",
            "properties": {
              "usd": {
                "type": "number"
              },
              "unpricedRequests": {
                "type": "number"
              },
              "subscriptionRequests": {
                "type": "number"
              },
              "requests": {
                "type": "number"
              }
            },
            "required": [
              "usd",
              "unpricedRequests",
              "subscriptionRequests",
              "requests"
            ],
            "additionalProperties": false
          },
          "avgLatencyMs": {
            "type": "number"
          }
        },
        "required": [
          "userId",
          "label",
          "email",
          "role",
          "keys",
          "requests",
          "totalTokens",
          "cachedTokens",
          "cost",
          "avgLatencyMs"
        ],
        "additionalProperties": false
      }
    },
    "total": {
      "type": "object",
      "properties": {
        "usd": {
          "type": "number"
        },
        "unpricedRequests": {
          "type": "number"
        },
        "subscriptionRequests": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        }
      },
      "required": [
        "usd",
        "unpricedRequests",
        "subscriptionRequests",
        "requests"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "from",
    "to",
    "members",
    "total"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/providers

reports.providers

Report spend per provider credential, against its declared limit, with live rate-limit headroom.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "credential": {
            "type": "string"
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "cost": {
            "type": "object",
            "properties": {
              "usd": {
                "type": "number"
              },
              "unpricedRequests": {
                "type": "number"
              },
              "subscriptionRequests": {
                "type": "number"
              },
              "requests": {
                "type": "number"
              }
            },
            "required": [
              "usd",
              "unpricedRequests",
              "subscriptionRequests",
              "requests"
            ],
            "additionalProperties": false
          },
          "limitUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "limitPeriod": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "month",
                  "30d"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "windowCost": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "usd": {
                    "type": "number"
                  },
                  "unpricedRequests": {
                    "type": "number"
                  },
                  "subscriptionRequests": {
                    "type": "number"
                  },
                  "requests": {
                    "type": "number"
                  }
                },
                "required": [
                  "usd",
                  "unpricedRequests",
                  "subscriptionRequests",
                  "requests"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "pctUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "headroom": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "pctLeft": {
                    "type": "number"
                  },
                  "tokensRemaining": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "tokensLimit": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "requestsRemaining": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "requestsLimit": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "capturedAt": {
                    "type": "string"
                  }
                },
                "required": [
                  "model",
                  "pctLeft",
                  "tokensRemaining",
                  "tokensLimit",
                  "requestsRemaining",
                  "requestsLimit",
                  "capturedAt"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "credential",
          "provider",
          "models",
          "requests",
          "totalTokens",
          "cost",
          "limitUsd",
          "limitPeriod",
          "windowCost",
          "pctUsd",
          "headroom"
        ],
        "additionalProperties": false
      }
    },
    "unattributed": {
      "type": "object",
      "properties": {
        "usd": {
          "type": "number"
        },
        "unpricedRequests": {
          "type": "number"
        },
        "subscriptionRequests": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        }
      },
      "required": [
        "usd",
        "unpricedRequests",
        "subscriptionRequests",
        "requests"
      ],
      "additionalProperties": false
    },
    "total": {
      "type": "object",
      "properties": {
        "usd": {
          "type": "number"
        },
        "unpricedRequests": {
          "type": "number"
        },
        "subscriptionRequests": {
          "type": "number"
        },
        "requests": {
          "type": "number"
        }
      },
      "required": [
        "usd",
        "unpricedRequests",
        "subscriptionRequests",
        "requests"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "from",
    "to",
    "rows",
    "unattributed",
    "total"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/developers

reports.developers

Report each developer's Claude Code usage from the client's own telemetry. Estimates, never spend.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "developers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "developer": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "keyIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "clients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sessions": {
            "type": "number"
          },
          "inputTokens": {
            "type": "number"
          },
          "outputTokens": {
            "type": "number"
          },
          "cacheReadTokens": {
            "type": "number"
          },
          "cacheCreationTokens": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "estimatedCostUsd": {
            "type": "number"
          },
          "linesAdded": {
            "type": "number"
          },
          "linesRemoved": {
            "type": "number"
          },
          "commits": {
            "type": "number"
          },
          "pullRequests": {
            "type": "number"
          },
          "activeSeconds": {
            "type": "number"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "model": {
                  "type": "string"
                },
                "totalTokens": {
                  "type": "number"
                }
              },
              "required": [
                "model",
                "totalTokens"
              ],
              "additionalProperties": false
            }
          },
          "gatewayRequests": {
            "type": "number"
          },
          "firstSeen": {
            "type": "string"
          },
          "lastSeen": {
            "type": "string"
          }
        },
        "required": [
          "developer",
          "name",
          "email",
          "keyIds",
          "clients",
          "sessions",
          "inputTokens",
          "outputTokens",
          "cacheReadTokens",
          "cacheCreationTokens",
          "totalTokens",
          "estimatedCostUsd",
          "linesAdded",
          "linesRemoved",
          "commits",
          "pullRequests",
          "activeSeconds",
          "models",
          "gatewayRequests",
          "firstSeen",
          "lastSeen"
        ],
        "additionalProperties": false
      }
    },
    "empty": {
      "type": "boolean"
    }
  },
  "required": [
    "from",
    "to",
    "developers",
    "empty"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/hooks

reports.hooks

Report what the managed Claude Code hooks decided: denials, unscreened work and screening outages.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "developers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "developer": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "keyId": {
            "type": "string"
          },
          "events": {
            "type": "number"
          },
          "denials": {
            "type": "number"
          },
          "unscreened": {
            "type": "number"
          },
          "outages": {
            "type": "number"
          },
          "lastSeen": {
            "type": "string"
          }
        },
        "required": [
          "developer",
          "name",
          "keyId",
          "events",
          "denials",
          "unscreened",
          "outages",
          "lastSeen"
        ],
        "additionalProperties": false
      }
    },
    "recent": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ts": {
            "type": "string"
          },
          "keyId": {
            "type": "string"
          },
          "sessionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "event": {
            "type": "string",
            "enum": [
              "UserPromptSubmit",
              "PreToolUse",
              "PostToolUse"
            ]
          },
          "tool": {
            "type": [
              "string",
              "null"
            ]
          },
          "decision": {
            "type": "string",
            "enum": [
              "allow",
              "deny",
              "audit"
            ]
          },
          "screened": {
            "type": "boolean"
          },
          "guardAction": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "allow",
                  "flag",
                  "block"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "unscreenedReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "guards": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "latencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "attributes": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          }
        },
        "required": [
          "ts",
          "keyId",
          "sessionId",
          "event",
          "tool",
          "decision",
          "screened",
          "guardAction",
          "unscreenedReason",
          "guards",
          "categories",
          "latencyMs",
          "attributes"
        ],
        "additionalProperties": false
      }
    },
    "totalOutages": {
      "type": "number"
    },
    "totalDenials": {
      "type": "number"
    }
  },
  "required": [
    "from",
    "to",
    "developers",
    "recent",
    "totalOutages",
    "totalDenials"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/economics

reports.economics

Read cost economics: spend per client, model and tool, with the driver decomposition and the subscription lane.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reports": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "result": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "spec": {
                    "type": "object",
                    "properties": {
                      "source": {
                        "type": "string",
                        "enum": [
                          "requests",
                          "tool_calls",
                          "agent_metrics",
                          "outcomes"
                        ]
                      },
                      "dimensions": {
                        "maxItems": 2,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "client",
                            "model",
                            "route",
                            "subject",
                            "key",
                            "channel",
                            "tag",
                            "session",
                            "server",
                            "tool",
                            "repository",
                            "day",
                            "week",
                            "month"
                          ]
                        }
                      },
                      "measures": {
                        "minItems": 1,
                        "maxItems": 40,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "requests",
                            "input_tokens",
                            "output_tokens",
                            "total_tokens",
                            "cached_tokens",
                            "cost_usd",
                            "unpriced_requests",
                            "users",
                            "sessions",
                            "active_hours",
                            "latency_avg_ms",
                            "latency_p95_ms",
                            "ttft_avg_ms",
                            "cost_share",
                            "request_share",
                            "cost_per_user",
                            "requests_per_user",
                            "cost_per_1k_requests",
                            "tokens_per_request",
                            "cost_per_1m_tokens",
                            "cost_per_1k_sessions",
                            "cost_per_active_hour",
                            "cache_hit_rate",
                            "cost_decomposition",
                            "calls",
                            "ok",
                            "failed",
                            "unknown",
                            "denied",
                            "pending",
                            "unpriced_calls",
                            "cost_per_ok_call",
                            "operations",
                            "estimated_cost_usd",
                            "merged_prs",
                            "reverted_prs",
                            "revert_rate",
                            "reviews",
                            "joined_prs",
                            "cost_per_merged_pr"
                          ]
                        }
                      },
                      "filters": {
                        "type": "object",
                        "propertyNames": {
                          "type": "string",
                          "enum": [
                            "client",
                            "model",
                            "route",
                            "subject",
                            "key",
                            "channel",
                            "tag",
                            "session",
                            "server",
                            "tool",
                            "repository",
                            "day",
                            "week",
                            "month"
                          ]
                        },
                        "additionalProperties": {
                          "maxItems": 50,
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 200
                          }
                        }
                      },
                      "range": {
                        "anyOf": [
                          {
                            "type": "string",
                            "enum": [
                              "7d",
                              "30d",
                              "mtd",
                              "last_month"
                            ]
                          },
                          {
                            "type": "object",
                            "properties": {
                              "from": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "to": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "from",
                              "to"
                            ],
                            "additionalProperties": false
                          }
                        ]
                      },
                      "compare": {
                        "type": "string",
                        "enum": [
                          "none",
                          "previous_period"
                        ]
                      },
                      "view": {
                        "type": "string",
                        "enum": [
                          "table",
                          "bar",
                          "line",
                          "stacked",
                          "waterfall"
                        ]
                      }
                    },
                    "required": [
                      "source",
                      "dimensions",
                      "measures",
                      "filters",
                      "range",
                      "compare",
                      "view"
                    ],
                    "additionalProperties": false
                  },
                  "window": {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "from",
                      "to"
                    ],
                    "additionalProperties": false
                  },
                  "previousWindow": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "from": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "to": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "from",
                          "to"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "groups": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "current": {
                          "anyOf": [
                            {
                              "type": "object",
                              "propertyNames": {
                                "type": "string",
                                "enum": [
                                  "requests",
                                  "input_tokens",
                                  "output_tokens",
                                  "total_tokens",
                                  "cached_tokens",
                                  "cost_usd",
                                  "unpriced_requests",
                                  "users",
                                  "sessions",
                                  "active_hours",
                                  "latency_avg_ms",
                                  "latency_p95_ms",
                                  "ttft_avg_ms",
                                  "cost_share",
                                  "request_share",
                                  "cost_per_user",
                                  "requests_per_user",
                                  "cost_per_1k_requests",
                                  "tokens_per_request",
                                  "cost_per_1m_tokens",
                                  "cost_per_1k_sessions",
                                  "cost_per_active_hour",
                                  "cache_hit_rate",
                                  "cost_decomposition",
                                  "calls",
                                  "ok",
                                  "failed",
                                  "unknown",
                                  "denied",
                                  "pending",
                                  "unpriced_calls",
                                  "cost_per_ok_call",
                                  "operations",
                                  "estimated_cost_usd",
                                  "merged_prs",
                                  "reverted_prs",
                                  "revert_rate",
                                  "reviews",
                                  "joined_prs",
                                  "cost_per_merged_pr"
                                ]
                              },
                              "additionalProperties": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "previous": {
                          "anyOf": [
                            {
                              "type": "object",
                              "propertyNames": {
                                "type": "string",
                                "enum": [
                                  "requests",
                                  "input_tokens",
                                  "output_tokens",
                                  "total_tokens",
                                  "cached_tokens",
                                  "cost_usd",
                                  "unpriced_requests",
                                  "users",
                                  "sessions",
                                  "active_hours",
                                  "latency_avg_ms",
                                  "latency_p95_ms",
                                  "ttft_avg_ms",
                                  "cost_share",
                                  "request_share",
                                  "cost_per_user",
                                  "requests_per_user",
                                  "cost_per_1k_requests",
                                  "tokens_per_request",
                                  "cost_per_1m_tokens",
                                  "cost_per_1k_sessions",
                                  "cost_per_active_hour",
                                  "cache_hit_rate",
                                  "cost_decomposition",
                                  "calls",
                                  "ok",
                                  "failed",
                                  "unknown",
                                  "denied",
                                  "pending",
                                  "unpriced_calls",
                                  "cost_per_ok_call",
                                  "operations",
                                  "estimated_cost_usd",
                                  "merged_prs",
                                  "reverted_prs",
                                  "revert_rate",
                                  "reviews",
                                  "joined_prs",
                                  "cost_per_merged_pr"
                                ]
                              },
                              "additionalProperties": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "delta": {
                          "anyOf": [
                            {
                              "type": "object",
                              "propertyNames": {
                                "type": "string",
                                "enum": [
                                  "requests",
                                  "input_tokens",
                                  "output_tokens",
                                  "total_tokens",
                                  "cached_tokens",
                                  "cost_usd",
                                  "unpriced_requests",
                                  "users",
                                  "sessions",
                                  "active_hours",
                                  "latency_avg_ms",
                                  "latency_p95_ms",
                                  "ttft_avg_ms",
                                  "cost_share",
                                  "request_share",
                                  "cost_per_user",
                                  "requests_per_user",
                                  "cost_per_1k_requests",
                                  "tokens_per_request",
                                  "cost_per_1m_tokens",
                                  "cost_per_1k_sessions",
                                  "cost_per_active_hour",
                                  "cache_hit_rate",
                                  "cost_decomposition",
                                  "calls",
                                  "ok",
                                  "failed",
                                  "unknown",
                                  "denied",
                                  "pending",
                                  "unpriced_calls",
                                  "cost_per_ok_call",
                                  "operations",
                                  "estimated_cost_usd",
                                  "merged_prs",
                                  "reverted_prs",
                                  "revert_rate",
                                  "reviews",
                                  "joined_prs",
                                  "cost_per_merged_pr"
                                ]
                              },
                              "additionalProperties": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "floor": {
                          "type": "boolean"
                        },
                        "previousFloor": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "groups",
                        "current",
                        "previous",
                        "delta",
                        "floor",
                        "previousFloor"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "total": {
                    "type": "object",
                    "properties": {
                      "groups": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "current": {
                        "anyOf": [
                          {
                            "type": "object",
                            "propertyNames": {
                              "type": "string",
                              "enum": [
                                "requests",
                                "input_tokens",
                                "output_tokens",
                                "total_tokens",
                                "cached_tokens",
                                "cost_usd",
                                "unpriced_requests",
                                "users",
                                "sessions",
                                "active_hours",
                                "latency_avg_ms",
                                "latency_p95_ms",
                                "ttft_avg_ms",
                                "cost_share",
                                "request_share",
                                "cost_per_user",
                                "requests_per_user",
                                "cost_per_1k_requests",
                                "tokens_per_request",
                                "cost_per_1m_tokens",
                                "cost_per_1k_sessions",
                                "cost_per_active_hour",
                                "cache_hit_rate",
                                "cost_decomposition",
                                "calls",
                                "ok",
                                "failed",
                                "unknown",
                                "denied",
                                "pending",
                                "unpriced_calls",
                                "cost_per_ok_call",
                                "operations",
                                "estimated_cost_usd",
                                "merged_prs",
                                "reverted_prs",
                                "revert_rate",
                                "reviews",
                                "joined_prs",
                                "cost_per_merged_pr"
                              ]
                            },
                            "additionalProperties": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "previous": {
                        "anyOf": [
                          {
                            "type": "object",
                            "propertyNames": {
                              "type": "string",
                              "enum": [
                                "requests",
                                "input_tokens",
                                "output_tokens",
                                "total_tokens",
                                "cached_tokens",
                                "cost_usd",
                                "unpriced_requests",
                                "users",
                                "sessions",
                                "active_hours",
                                "latency_avg_ms",
                                "latency_p95_ms",
                                "ttft_avg_ms",
                                "cost_share",
                                "request_share",
                                "cost_per_user",
                                "requests_per_user",
                                "cost_per_1k_requests",
                                "tokens_per_request",
                                "cost_per_1m_tokens",
                                "cost_per_1k_sessions",
                                "cost_per_active_hour",
                                "cache_hit_rate",
                                "cost_decomposition",
                                "calls",
                                "ok",
                                "failed",
                                "unknown",
                                "denied",
                                "pending",
                                "unpriced_calls",
                                "cost_per_ok_call",
                                "operations",
                                "estimated_cost_usd",
                                "merged_prs",
                                "reverted_prs",
                                "revert_rate",
                                "reviews",
                                "joined_prs",
                                "cost_per_merged_pr"
                              ]
                            },
                            "additionalProperties": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "delta": {
                        "anyOf": [
                          {
                            "type": "object",
                            "propertyNames": {
                              "type": "string",
                              "enum": [
                                "requests",
                                "input_tokens",
                                "output_tokens",
                                "total_tokens",
                                "cached_tokens",
                                "cost_usd",
                                "unpriced_requests",
                                "users",
                                "sessions",
                                "active_hours",
                                "latency_avg_ms",
                                "latency_p95_ms",
                                "ttft_avg_ms",
                                "cost_share",
                                "request_share",
                                "cost_per_user",
                                "requests_per_user",
                                "cost_per_1k_requests",
                                "tokens_per_request",
                                "cost_per_1m_tokens",
                                "cost_per_1k_sessions",
                                "cost_per_active_hour",
                                "cache_hit_rate",
                                "cost_decomposition",
                                "calls",
                                "ok",
                                "failed",
                                "unknown",
                                "denied",
                                "pending",
                                "unpriced_calls",
                                "cost_per_ok_call",
                                "operations",
                                "estimated_cost_usd",
                                "merged_prs",
                                "reverted_prs",
                                "revert_rate",
                                "reviews",
                                "joined_prs",
                                "cost_per_merged_pr"
                              ]
                            },
                            "additionalProperties": {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "floor": {
                        "type": "boolean"
                      },
                      "previousFloor": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "groups",
                      "current",
                      "previous",
                      "delta",
                      "floor",
                      "previousFloor"
                    ],
                    "additionalProperties": false
                  },
                  "decomposition": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "previousUsd": {
                            "type": "number"
                          },
                          "currentUsd": {
                            "type": "number"
                          },
                          "deltaUsd": {
                            "type": "number"
                          },
                          "parts": {
                            "type": "object",
                            "properties": {
                              "users": {
                                "type": "number"
                              },
                              "requestsPerUser": {
                                "type": "number"
                              },
                              "inputTokensPerRequest": {
                                "type": "number"
                              },
                              "outputTokensPerRequest": {
                                "type": "number"
                              },
                              "pricePerToken": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "users",
                              "requestsPerUser",
                              "inputTokensPerRequest",
                              "outputTokensPerRequest",
                              "pricePerToken"
                            ],
                            "additionalProperties": false
                          },
                          "unmodelledUsd": {
                            "type": "number"
                          },
                          "floor": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "previousUsd",
                          "currentUsd",
                          "deltaUsd",
                          "parts",
                          "unmodelledUsd",
                          "floor"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "coverage": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "dimensionsSince": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "rowsBefore": {
                            "type": "number"
                          },
                          "previousRowsBefore": {
                            "type": [
                              "number",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "dimensionsSince",
                          "rowsBefore",
                          "previousRowsBefore"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "spec",
                  "window",
                  "previousWindow",
                  "rows",
                  "total",
                  "decomposition",
                  "coverage"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "result"
        ],
        "additionalProperties": false
      }
    },
    "subscription": {
      "type": "object",
      "properties": {
        "spec": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "requests",
                "tool_calls",
                "agent_metrics",
                "outcomes"
              ]
            },
            "dimensions": {
              "maxItems": 2,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              }
            },
            "measures": {
              "minItems": 1,
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "requests",
                  "input_tokens",
                  "output_tokens",
                  "total_tokens",
                  "cached_tokens",
                  "cost_usd",
                  "unpriced_requests",
                  "users",
                  "sessions",
                  "active_hours",
                  "latency_avg_ms",
                  "latency_p95_ms",
                  "ttft_avg_ms",
                  "cost_share",
                  "request_share",
                  "cost_per_user",
                  "requests_per_user",
                  "cost_per_1k_requests",
                  "tokens_per_request",
                  "cost_per_1m_tokens",
                  "cost_per_1k_sessions",
                  "cost_per_active_hour",
                  "cache_hit_rate",
                  "cost_decomposition",
                  "calls",
                  "ok",
                  "failed",
                  "unknown",
                  "denied",
                  "pending",
                  "unpriced_calls",
                  "cost_per_ok_call",
                  "operations",
                  "estimated_cost_usd",
                  "merged_prs",
                  "reverted_prs",
                  "revert_rate",
                  "reviews",
                  "joined_prs",
                  "cost_per_merged_pr"
                ]
              }
            },
            "filters": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              },
              "additionalProperties": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            },
            "range": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "7d",
                    "30d",
                    "mtd",
                    "last_month"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "compare": {
              "type": "string",
              "enum": [
                "none",
                "previous_period"
              ]
            },
            "view": {
              "type": "string",
              "enum": [
                "table",
                "bar",
                "line",
                "stacked",
                "waterfall"
              ]
            }
          },
          "required": [
            "source",
            "dimensions",
            "measures",
            "filters",
            "range",
            "compare",
            "view"
          ],
          "additionalProperties": false
        },
        "window": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "string",
                "null"
              ]
            },
            "to": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ],
          "additionalProperties": false
        },
        "previousWindow": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "groups": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "current": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "previous": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "delta": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "floor": {
                "type": "boolean"
              },
              "previousFloor": {
                "type": "boolean"
              }
            },
            "required": [
              "groups",
              "current",
              "previous",
              "delta",
              "floor",
              "previousFloor"
            ],
            "additionalProperties": false
          }
        },
        "total": {
          "type": "object",
          "properties": {
            "groups": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "current": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "previous": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "delta": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "floor": {
              "type": "boolean"
            },
            "previousFloor": {
              "type": "boolean"
            }
          },
          "required": [
            "groups",
            "current",
            "previous",
            "delta",
            "floor",
            "previousFloor"
          ],
          "additionalProperties": false
        },
        "decomposition": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "previousUsd": {
                  "type": "number"
                },
                "currentUsd": {
                  "type": "number"
                },
                "deltaUsd": {
                  "type": "number"
                },
                "parts": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "number"
                    },
                    "requestsPerUser": {
                      "type": "number"
                    },
                    "inputTokensPerRequest": {
                      "type": "number"
                    },
                    "outputTokensPerRequest": {
                      "type": "number"
                    },
                    "pricePerToken": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "users",
                    "requestsPerUser",
                    "inputTokensPerRequest",
                    "outputTokensPerRequest",
                    "pricePerToken"
                  ],
                  "additionalProperties": false
                },
                "unmodelledUsd": {
                  "type": "number"
                },
                "floor": {
                  "type": "boolean"
                }
              },
              "required": [
                "previousUsd",
                "currentUsd",
                "deltaUsd",
                "parts",
                "unmodelledUsd",
                "floor"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "coverage": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "dimensionsSince": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "rowsBefore": {
                  "type": "number"
                },
                "previousRowsBefore": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "dimensionsSince",
                "rowsBefore",
                "previousRowsBefore"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "spec",
        "window",
        "previousWindow",
        "rows",
        "total",
        "decomposition",
        "coverage"
      ],
      "additionalProperties": false
    },
    "agentEstimate": {
      "type": "object",
      "properties": {
        "spec": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "requests",
                "tool_calls",
                "agent_metrics",
                "outcomes"
              ]
            },
            "dimensions": {
              "maxItems": 2,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              }
            },
            "measures": {
              "minItems": 1,
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "requests",
                  "input_tokens",
                  "output_tokens",
                  "total_tokens",
                  "cached_tokens",
                  "cost_usd",
                  "unpriced_requests",
                  "users",
                  "sessions",
                  "active_hours",
                  "latency_avg_ms",
                  "latency_p95_ms",
                  "ttft_avg_ms",
                  "cost_share",
                  "request_share",
                  "cost_per_user",
                  "requests_per_user",
                  "cost_per_1k_requests",
                  "tokens_per_request",
                  "cost_per_1m_tokens",
                  "cost_per_1k_sessions",
                  "cost_per_active_hour",
                  "cache_hit_rate",
                  "cost_decomposition",
                  "calls",
                  "ok",
                  "failed",
                  "unknown",
                  "denied",
                  "pending",
                  "unpriced_calls",
                  "cost_per_ok_call",
                  "operations",
                  "estimated_cost_usd",
                  "merged_prs",
                  "reverted_prs",
                  "revert_rate",
                  "reviews",
                  "joined_prs",
                  "cost_per_merged_pr"
                ]
              }
            },
            "filters": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              },
              "additionalProperties": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            },
            "range": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "7d",
                    "30d",
                    "mtd",
                    "last_month"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "compare": {
              "type": "string",
              "enum": [
                "none",
                "previous_period"
              ]
            },
            "view": {
              "type": "string",
              "enum": [
                "table",
                "bar",
                "line",
                "stacked",
                "waterfall"
              ]
            }
          },
          "required": [
            "source",
            "dimensions",
            "measures",
            "filters",
            "range",
            "compare",
            "view"
          ],
          "additionalProperties": false
        },
        "window": {
          "type": "object",
          "properties": {
            "from": {
              "type": [
                "string",
                "null"
              ]
            },
            "to": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "from",
            "to"
          ],
          "additionalProperties": false
        },
        "previousWindow": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "from": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "from",
                "to"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "groups": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "current": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "previous": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "delta": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "enum": [
                        "requests",
                        "input_tokens",
                        "output_tokens",
                        "total_tokens",
                        "cached_tokens",
                        "cost_usd",
                        "unpriced_requests",
                        "users",
                        "sessions",
                        "active_hours",
                        "latency_avg_ms",
                        "latency_p95_ms",
                        "ttft_avg_ms",
                        "cost_share",
                        "request_share",
                        "cost_per_user",
                        "requests_per_user",
                        "cost_per_1k_requests",
                        "tokens_per_request",
                        "cost_per_1m_tokens",
                        "cost_per_1k_sessions",
                        "cost_per_active_hour",
                        "cache_hit_rate",
                        "cost_decomposition",
                        "calls",
                        "ok",
                        "failed",
                        "unknown",
                        "denied",
                        "pending",
                        "unpriced_calls",
                        "cost_per_ok_call",
                        "operations",
                        "estimated_cost_usd",
                        "merged_prs",
                        "reverted_prs",
                        "revert_rate",
                        "reviews",
                        "joined_prs",
                        "cost_per_merged_pr"
                      ]
                    },
                    "additionalProperties": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "floor": {
                "type": "boolean"
              },
              "previousFloor": {
                "type": "boolean"
              }
            },
            "required": [
              "groups",
              "current",
              "previous",
              "delta",
              "floor",
              "previousFloor"
            ],
            "additionalProperties": false
          }
        },
        "total": {
          "type": "object",
          "properties": {
            "groups": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "current": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "previous": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "delta": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "enum": [
                      "requests",
                      "input_tokens",
                      "output_tokens",
                      "total_tokens",
                      "cached_tokens",
                      "cost_usd",
                      "unpriced_requests",
                      "users",
                      "sessions",
                      "active_hours",
                      "latency_avg_ms",
                      "latency_p95_ms",
                      "ttft_avg_ms",
                      "cost_share",
                      "request_share",
                      "cost_per_user",
                      "requests_per_user",
                      "cost_per_1k_requests",
                      "tokens_per_request",
                      "cost_per_1m_tokens",
                      "cost_per_1k_sessions",
                      "cost_per_active_hour",
                      "cache_hit_rate",
                      "cost_decomposition",
                      "calls",
                      "ok",
                      "failed",
                      "unknown",
                      "denied",
                      "pending",
                      "unpriced_calls",
                      "cost_per_ok_call",
                      "operations",
                      "estimated_cost_usd",
                      "merged_prs",
                      "reverted_prs",
                      "revert_rate",
                      "reviews",
                      "joined_prs",
                      "cost_per_merged_pr"
                    ]
                  },
                  "additionalProperties": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "floor": {
              "type": "boolean"
            },
            "previousFloor": {
              "type": "boolean"
            }
          },
          "required": [
            "groups",
            "current",
            "previous",
            "delta",
            "floor",
            "previousFloor"
          ],
          "additionalProperties": false
        },
        "decomposition": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "previousUsd": {
                  "type": "number"
                },
                "currentUsd": {
                  "type": "number"
                },
                "deltaUsd": {
                  "type": "number"
                },
                "parts": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "number"
                    },
                    "requestsPerUser": {
                      "type": "number"
                    },
                    "inputTokensPerRequest": {
                      "type": "number"
                    },
                    "outputTokensPerRequest": {
                      "type": "number"
                    },
                    "pricePerToken": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "users",
                    "requestsPerUser",
                    "inputTokensPerRequest",
                    "outputTokensPerRequest",
                    "pricePerToken"
                  ],
                  "additionalProperties": false
                },
                "unmodelledUsd": {
                  "type": "number"
                },
                "floor": {
                  "type": "boolean"
                }
              },
              "required": [
                "previousUsd",
                "currentUsd",
                "deltaUsd",
                "parts",
                "unmodelledUsd",
                "floor"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "coverage": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "dimensionsSince": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "rowsBefore": {
                  "type": "number"
                },
                "previousRowsBefore": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "dimensionsSince",
                "rowsBefore",
                "previousRowsBefore"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "spec",
        "window",
        "previousWindow",
        "rows",
        "total",
        "decomposition",
        "coverage"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "reports",
    "subscription",
    "agentEstimate"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/tool-calls

reports.tool-calls

Report tool calls through /mcp per tool, server, person or key: calls, outcomes, refusals, cost and latency.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groupBy": {
      "type": "string",
      "enum": [
        "tool",
        "server",
        "person",
        "key"
      ]
    },
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "calls": {
            "type": "number"
          },
          "dispatched": {
            "type": "number"
          },
          "denied": {
            "type": "number"
          },
          "pending": {
            "type": "number"
          },
          "failed": {
            "type": "number"
          },
          "unknown": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedCalls": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "p95LatencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "group",
          "calls",
          "dispatched",
          "denied",
          "pending",
          "failed",
          "unknown",
          "costUsd",
          "unpricedCalls",
          "avgLatencyMs",
          "p95LatencyMs",
          "subjectName"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "groupBy",
    "from",
    "to",
    "rows"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/agent-metrics

reports.agent-metrics

Report the usage the agents reported themselves, per client, model, person, session, key or user. Never spend.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groupBy": {
      "type": "string",
      "enum": [
        "client",
        "model",
        "subject",
        "session",
        "key",
        "user"
      ]
    },
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "operations": {
            "type": "number"
          },
          "operationSeconds": {
            "type": "number"
          },
          "inputTokens": {
            "type": "number"
          },
          "outputTokens": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "sessions": {
            "type": "number"
          },
          "estimatedCostUsd": {
            "type": "number"
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "group",
          "operations",
          "operationSeconds",
          "inputTokens",
          "outputTokens",
          "totalTokens",
          "sessions",
          "estimatedCostUsd",
          "subjectName"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "groupBy",
    "from",
    "to",
    "rows"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/security

reports.security

Report security events: refused and failed requests, and the security-relevant audit entries.

Role
owner
Scope
audit:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "blocked": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "route": {
            "type": "string"
          },
          "keyId": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "lastSeen": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "route",
          "keyId",
          "requests",
          "lastSeen"
        ],
        "additionalProperties": false
      }
    },
    "counts": {
      "type": "object",
      "properties": {
        "unauthorized": {
          "type": "number"
        },
        "forbidden": {
          "type": "number"
        },
        "rateLimited": {
          "type": "number"
        },
        "upstreamErrors": {
          "type": "number"
        }
      },
      "required": [
        "unauthorized",
        "forbidden",
        "rateLimited",
        "upstreamErrors"
      ],
      "additionalProperties": false
    },
    "audit": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number"
          },
          "ts": {
            "type": "string"
          },
          "actorType": {
            "type": "string",
            "enum": [
              "user",
              "token"
            ]
          },
          "actorUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "actorEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "actorTokenId": {
            "type": [
              "string",
              "null"
            ]
          },
          "action": {
            "type": "string"
          },
          "resourceType": {
            "type": [
              "string",
              "null"
            ]
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "before": {},
          "after": {},
          "ip": {
            "type": [
              "string",
              "null"
            ]
          },
          "userAgent": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "reasonCategory": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "ts",
          "actorType",
          "actorUserId",
          "actorEmail",
          "actorTokenId",
          "action",
          "resourceType",
          "resourceId",
          "before",
          "after",
          "ip",
          "userAgent",
          "reason",
          "reasonCategory"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "from",
    "to",
    "blocked",
    "counts",
    "audit"
  ],
  "additionalProperties": false
}

GET /api/v1/status

status.read

Read each catalog model's health: up, degraded, down or unknown, with recent traffic, errors and latency.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "models": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "providerModel": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "credential": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "up",
              "degraded",
              "down",
              "unknown"
            ]
          },
          "probeHealthy": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "probeError": {
            "type": [
              "string",
              "null"
            ]
          },
          "requests": {
            "type": "number"
          },
          "errorRate": {
            "type": [
              "number",
              "null"
            ]
          },
          "avgLatencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "p95LatencyMs": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "model",
          "providerModel",
          "provider",
          "credential",
          "state",
          "probeHealthy",
          "probeError",
          "requests",
          "errorRate",
          "avgLatencyMs",
          "p95LatencyMs"
        ],
        "additionalProperties": false
      }
    },
    "windowMinutes": {
      "type": "number"
    }
  },
  "required": [
    "models",
    "windowMinutes"
  ],
  "additionalProperties": false
}

GET /api/v1/batches

batches.list

List batch jobs, newest first, each with its per-model usage ledger and deferred cost.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string"
          },
          "keyId": {
            "type": "string"
          },
          "endpoint": {
            "type": [
              "string",
              "null"
            ]
          },
          "inputFileId": {
            "type": [
              "string",
              "null"
            ]
          },
          "outputFileId": {
            "type": [
              "string",
              "null"
            ]
          },
          "errorFileId": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "requestCounts": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ]
          },
          "submittedAt": {
            "type": "string"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reconciledAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reconcileAttempts": {
            "type": "number"
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "partial": {
            "type": "boolean"
          },
          "usage": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "batchId": {
                  "type": "string"
                },
                "model": {
                  "type": "string"
                },
                "logicalRequests": {
                  "type": "number"
                },
                "promptTokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "completionTokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "totalTokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "cachedTokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "costUsd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "costSource": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "upstream",
                        "catalog",
                        "catalog_interactive"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "effectiveAt": {
                  "type": "string"
                }
              },
              "required": [
                "batchId",
                "model",
                "logicalRequests",
                "promptTokens",
                "completionTokens",
                "totalTokens",
                "cachedTokens",
                "costUsd",
                "costSource",
                "effectiveAt"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "batchId",
          "keyId",
          "endpoint",
          "inputFileId",
          "outputFileId",
          "errorFileId",
          "status",
          "requestCounts",
          "submittedAt",
          "completedAt",
          "reconciledAt",
          "reconcileAttempts",
          "lastError",
          "partial",
          "usage"
        ],
        "additionalProperties": false
      }
    },
    "caveat": {
      "type": "string"
    }
  },
  "required": [
    "rows",
    "caveat"
  ],
  "additionalProperties": false
}

GET /api/v1/observability/metrics

observability.metrics

Read daily request, token, cost and latency trends from Langfuse over a window (default: 14 days).

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "configured": {
      "type": "boolean"
    },
    "from": {
      "type": [
        "string",
        "null"
      ]
    },
    "to": {
      "type": [
        "string",
        "null"
      ]
    },
    "points": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "totalTokens": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": "number"
          }
        },
        "required": [
          "date",
          "requests",
          "totalTokens",
          "costUsd",
          "avgLatencyMs"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "configured",
    "from",
    "to",
    "points"
  ],
  "additionalProperties": false
}

GET /api/v1/logs

logs.list

List recent request-log rows, newest first: route, key, model, status, latency, tokens and cost. Never a body.

Role
viewer
Scope
logs:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number"
          },
          "ts": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "api",
              "subscription"
            ]
          },
          "route": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "keyId": {
            "type": "string"
          },
          "subjectType": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "human",
                  "workload"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "subjectId": {
            "type": [
              "string",
              "null"
            ]
          },
          "client": {
            "type": [
              "string",
              "null"
            ]
          },
          "sessionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "endUser": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "streamed": {
            "type": "boolean"
          },
          "aborted": {
            "type": "boolean"
          },
          "latencyMs": {
            "type": "number"
          },
          "ttftMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "promptTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "completionTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "totalTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "cachedTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "cacheWriteTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "imageCount": {
            "type": [
              "number",
              "null"
            ]
          },
          "audioSeconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "characters": {
            "type": [
              "number",
              "null"
            ]
          },
          "documents": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "costSource": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "upstream",
                  "catalog",
                  "catalog_interactive"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "guardFindings": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "logId": {
                      "type": "number"
                    },
                    "stage": {
                      "type": "string",
                      "enum": [
                        "request",
                        "response",
                        "tool_call",
                        "tool_result"
                      ]
                    },
                    "ruleId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "guard": {
                      "type": "string"
                    },
                    "ruleType": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "action": {
                      "type": "string"
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "logId",
                    "stage",
                    "ruleId",
                    "guard",
                    "ruleType",
                    "action",
                    "category"
                  ],
                  "additionalProperties": false
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "packTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "packs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number"
                },
                "logId": {
                  "type": "number"
                },
                "packId": {
                  "type": "string"
                },
                "versionId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "assignmentId": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string"
                },
                "tokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "chunkIndexes": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "number"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "id",
                "logId",
                "packId",
                "versionId",
                "assignmentId",
                "outcome",
                "tokens"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "ts",
          "endpoint",
          "channel",
          "keyId",
          "subjectType",
          "subjectId",
          "client",
          "sessionId",
          "tags",
          "status",
          "aborted",
          "latencyMs",
          "ttftMs",
          "cachedTokens",
          "cacheWriteTokens",
          "imageCount",
          "audioSeconds",
          "characters",
          "documents",
          "costUsd",
          "costSource",
          "guardFindings",
          "packTokens",
          "packs"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "rows"
  ],
  "additionalProperties": false
}

GET /api/v1/observability/traces

observability.traces.list

List Langfuse traces (names, timings, costs, tags), filtered by window, user, tag or name. Never a body.

Role
viewer
Scope
logs:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "configured": {
      "type": "boolean"
    },
    "traces": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "user": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "latencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "observationCount": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "timestamp",
          "name",
          "user",
          "tags",
          "latencyMs",
          "costUsd",
          "observationCount"
        ],
        "additionalProperties": false
      }
    },
    "page": {
      "type": "number"
    },
    "totalPages": {
      "type": "number"
    },
    "totalItems": {
      "type": "number"
    }
  },
  "required": [
    "configured",
    "traces",
    "page",
    "totalPages",
    "totalItems"
  ],
  "additionalProperties": false
}

GET /api/v1/audit

audit.list

List audit-log entries, newest first: who changed what, when, and the before and after.

Role
owner
Scope
audit:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number"
          },
          "ts": {
            "type": "string"
          },
          "actorType": {
            "type": "string",
            "enum": [
              "user",
              "token"
            ]
          },
          "actorUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "actorEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "actorTokenId": {
            "type": [
              "string",
              "null"
            ]
          },
          "action": {
            "type": "string"
          },
          "resourceType": {
            "type": [
              "string",
              "null"
            ]
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "before": {},
          "after": {},
          "ip": {
            "type": [
              "string",
              "null"
            ]
          },
          "userAgent": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "reasonCategory": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "ts",
          "actorType",
          "actorUserId",
          "actorEmail",
          "actorTokenId",
          "action",
          "resourceType",
          "resourceId",
          "before",
          "after",
          "ip",
          "userAgent",
          "reason",
          "reasonCategory"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "entries"
  ],
  "additionalProperties": false
}

GET /api/v1/keys

keys.list

List client keys with their owner, route and ZDR fences, tool grant, team, budget and spend. Never a secret.

Role
viewer
Scope
keys:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keys": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "keyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          },
          "assignee": {
            "type": [
              "string",
              "null"
            ]
          },
          "ownerUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "allowedRoutes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pinnedRoute": {
            "type": [
              "string",
              "null"
            ]
          },
          "requireZdr": {
            "type": "boolean"
          },
          "toolAccess": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "servers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "resources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "groups": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "readOnly": {
                    "type": "boolean"
                  },
                  "version": {
                    "type": "number"
                  },
                  "syncedVersion": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "syncedAt": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "syncError": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "none",
                      "drift",
                      "ready"
                    ]
                  }
                },
                "required": [
                  "servers",
                  "tools",
                  "resources",
                  "prompts",
                  "groups",
                  "readOnly",
                  "version",
                  "syncedVersion",
                  "syncedAt",
                  "syncError",
                  "status"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "teamId": {
            "type": [
              "string",
              "null"
            ]
          },
          "budget": {
            "type": [
              "number",
              "null"
            ]
          },
          "budgetDuration": {
            "type": [
              "string",
              "null"
            ]
          },
          "spend": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "revoked"
            ]
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "isCopilot": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "keyId",
          "label",
          "assignee",
          "ownerUserId",
          "ownerEmail",
          "allowedRoutes",
          "pinnedRoute",
          "budget",
          "budgetDuration",
          "spend",
          "status",
          "createdAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "keys"
  ],
  "additionalProperties": false
}

GET /api/v1/users

users.list

List console users with their role, status, identity provider and last sign-in.

Role
owner
Scope
users:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "member",
              "viewer",
              "admin",
              "owner"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "active",
              "disabled"
            ]
          },
          "authProvider": {
            "type": "string"
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "lastLoginAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "email",
          "name",
          "role",
          "status",
          "authProvider",
          "externalId",
          "createdAt",
          "lastLoginAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "users"
  ],
  "additionalProperties": false
}

GET /api/v1/users/directory

users.directory

List the accounts that can own a key: id, name and email only. Disabled accounts are left out.

Role
admin
Scope
users:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "email"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "users"
  ],
  "additionalProperties": false
}

GET /api/v1/credentials

credentials.list

List provider credentials: name, provider and endpoint. Never the provider key.

Role
viewer
Scope
providers:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "credentials": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "apiBase": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "provider",
          "apiBase"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "credentials"
  ],
  "additionalProperties": false
}

GET /api/v1/credentials/usage

credentials.usage

Read each provider credential's usage in its limit window, as tokens, USD and percent of the limit.

Role
viewer
Scope
providers:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "usage": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "credential": {
            "type": "string"
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "period": {
            "type": "string",
            "enum": [
              "month",
              "30d"
            ]
          },
          "windowStart": {
            "type": "string"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "usedTokens": {
            "type": "number"
          },
          "usedUsd": {
            "type": "number"
          },
          "unpricedModels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "limitUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "pctTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "pctUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "headroom": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "pctLeft": {
                    "type": "number"
                  },
                  "tokensRemaining": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "tokensLimit": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "requestsRemaining": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "requestsLimit": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "capturedAt": {
                    "type": "string"
                  }
                },
                "required": [
                  "model",
                  "pctLeft",
                  "tokensRemaining",
                  "tokensLimit",
                  "requestsRemaining",
                  "requestsLimit",
                  "capturedAt"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "credential",
          "provider",
          "period",
          "windowStart",
          "models",
          "usedTokens",
          "usedUsd",
          "unpricedModels",
          "limitTokens",
          "limitUsd",
          "pctTokens",
          "pctUsd",
          "pct",
          "headroom"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "usage"
  ],
  "additionalProperties": false
}

GET /api/v1/models/catalog

models.catalog

List the routable models with their provider model, credential and source.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "models": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "providerModel": {
            "type": "string"
          },
          "credentialName": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "config",
              "database"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "providerModel",
          "credentialName",
          "source"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "models"
  ],
  "additionalProperties": false
}

GET /api/v1/prices

prices.list

List the rates the gateway prices each request with, per model, and where each rate came from.

Role
viewer
Scope
providers:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "prices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "inputUsdPerMtok": {
            "type": [
              "number",
              "null"
            ]
          },
          "outputUsdPerMtok": {
            "type": [
              "number",
              "null"
            ]
          },
          "cacheReadUsdPerMtok": {
            "type": [
              "number",
              "null"
            ]
          },
          "cacheWriteUsdPerMtok": {
            "type": [
              "number",
              "null"
            ]
          },
          "imageUsdPerUnit": {
            "type": [
              "number",
              "null"
            ]
          },
          "audioUsdPerSecond": {
            "type": [
              "number",
              "null"
            ]
          },
          "characterUsdPerMchar": {
            "type": [
              "number",
              "null"
            ]
          },
          "maxInputTokens": {
            "type": [
              "number",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "chassis",
              "manual"
            ]
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "model",
          "inputUsdPerMtok",
          "outputUsdPerMtok",
          "cacheReadUsdPerMtok",
          "cacheWriteUsdPerMtok",
          "imageUsdPerUnit",
          "audioUsdPerSecond",
          "characterUsdPerMchar",
          "maxInputTokens",
          "source",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "prices"
  ],
  "additionalProperties": false
}

GET /api/v1/model-policy

model-policy.list

List the per-model zero-data-retention attestations that ZDR-only keys and routes are routed on.

Role
viewer
Scope
providers:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "policies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "zdr": {
            "type": "boolean"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "model",
          "zdr",
          "note",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "policies"
  ],
  "additionalProperties": false
}

GET /api/v1/providers

providers.list

List the providers and models the chassis registry knows, for choosing a model to add.

Role
viewer
Scope
providers:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "model": {
                  "type": "string"
                },
                "providerModel": {
                  "type": "string"
                },
                "mode": {
                  "type": "string"
                }
              },
              "required": [
                "model",
                "providerModel",
                "mode"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "models"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "providers"
  ],
  "additionalProperties": false
}

POST /api/v1/keys

keys.create

Mint a client key; its secret is returned once and never again. Human session only.

Role
admin
Scope
keys:write
Idempotency key
required
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "minLength": 1
    },
    "ownerUserId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "assignee": {
      "type": "string"
    },
    "budget": {
      "type": "number",
      "minimum": 0
    },
    "budgetDuration": {
      "type": "string",
      "minLength": 1
    },
    "allowedRoutes": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "pinnedRoute": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "label"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "key": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "keyId": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "assignee": {
          "type": [
            "string",
            "null"
          ]
        },
        "ownerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "ownerEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "allowedRoutes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "pinnedRoute": {
          "type": [
            "string",
            "null"
          ]
        },
        "requireZdr": {
          "type": "boolean"
        },
        "toolAccess": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "servers": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "tools": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "resources": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "prompts": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "groups": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "readOnly": {
                  "type": "boolean"
                },
                "version": {
                  "type": "number"
                },
                "syncedVersion": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "syncedAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "syncError": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "none",
                    "drift",
                    "ready"
                  ]
                }
              },
              "required": [
                "servers",
                "tools",
                "resources",
                "prompts",
                "groups",
                "readOnly",
                "version",
                "syncedVersion",
                "syncedAt",
                "syncError",
                "status"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "teamId": {
          "type": [
            "string",
            "null"
          ]
        },
        "budget": {
          "type": [
            "number",
            "null"
          ]
        },
        "budgetDuration": {
          "type": [
            "string",
            "null"
          ]
        },
        "spend": {
          "type": "number"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked"
          ]
        },
        "createdAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "isCopilot": {
          "type": "boolean"
        },
        "secret": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "keyId",
        "label",
        "assignee",
        "ownerUserId",
        "ownerEmail",
        "allowedRoutes",
        "pinnedRoute",
        "budget",
        "budgetDuration",
        "spend",
        "status",
        "createdAt",
        "secret"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false
}

DELETE /api/v1/keys/{id}

keys.revoke

Revoke a client key by its chassis id; clients using it stop at once. The copilot's own key needs force=true.

Role
admin
Scope
keys:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/owner

keys.owner.set

Set or clear the person a key belongs to — whose usage its spend is reported under. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "userId": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "keyId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "ownerUserId": {
      "type": [
        "string",
        "null"
      ]
    },
    "ownerEmail": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "ownerUserId",
    "ownerEmail"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/pin

keys.pin.set

Pin a key to one route, which skips the classifier, or clear its pin. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "route": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "keyId",
    "route"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "pinned": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "pinned"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/repair

keys.identity.repair

Record our id for a key this console did not create, so it can be owned, scoped and pinned. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string"
    },
    "alreadyRecorded": {
      "type": "boolean"
    }
  },
  "required": [
    "keyId",
    "alreadyRecorded"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/scope

keys.scope.set

Set the routes a key may use; an empty list allows every route. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "routes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "keyId",
    "routes"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "routes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ok",
    "routes"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/zdr

keys.zdr.set

Require, or stop requiring, ZDR-attested models for a key. Turning it on can refuse its traffic at once. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "required": {
      "type": "boolean"
    }
  },
  "required": [
    "keyId",
    "required"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "requireZdr": {
      "type": "boolean"
    }
  },
  "required": [
    "ok",
    "requireZdr"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/tools

keys.tools.set

Set which MCP tools, resources and prompts a key may use, then sync the chassis copy. Human session only.

Role
admin
Scope
keys:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "servers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "readOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "keyId",
    "servers",
    "tools",
    "readOnly"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "access": {
      "type": "object",
      "properties": {
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "readOnly": {
          "type": "boolean"
        },
        "version": {
          "type": "number"
        },
        "syncedVersion": {
          "type": [
            "number",
            "null"
          ]
        },
        "syncedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "syncError": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "drift",
            "ready"
          ]
        }
      },
      "required": [
        "servers",
        "tools",
        "resources",
        "prompts",
        "groups",
        "readOnly",
        "version",
        "syncedVersion",
        "syncedAt",
        "syncError",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "access"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/tools/resync

keys.tools.resync

Push a key's stored tool grant to the chassis again, after a failed sync. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "keyId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "access": {
      "type": "object",
      "properties": {
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "readOnly": {
          "type": "boolean"
        },
        "version": {
          "type": "number"
        },
        "syncedVersion": {
          "type": [
            "number",
            "null"
          ]
        },
        "syncedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "syncError": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "drift",
            "ready"
          ]
        }
      },
      "required": [
        "servers",
        "tools",
        "resources",
        "prompts",
        "groups",
        "readOnly",
        "version",
        "syncedVersion",
        "syncedAt",
        "syncError",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "access"
  ],
  "additionalProperties": false
}

DELETE /api/v1/keys/tools

keys.tools.revoke

Remove a key's tool grant: it may then call no tool. Human session only.

Role
admin
Scope
keys:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/keys/team

keys.team.set

Put a key in a team, whose tool grant is AND-ed with the key's, or take it out. Human session only.

Role
admin
Scope
keys:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "teamId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "keyId",
    "teamId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "teamId": {
      "type": [
        "string",
        "null"
      ]
    },
    "access": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "servers": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "tools": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "prompts": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "groups": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "readOnly": {
              "type": "boolean"
            },
            "version": {
              "type": "number"
            },
            "syncedVersion": {
              "type": [
                "number",
                "null"
              ]
            },
            "syncedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "syncError": {
              "type": [
                "string",
                "null"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "none",
                "drift",
                "ready"
              ]
            }
          },
          "required": [
            "servers",
            "tools",
            "resources",
            "prompts",
            "groups",
            "readOnly",
            "version",
            "syncedVersion",
            "syncedAt",
            "syncError",
            "status"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "teamId",
    "access"
  ],
  "additionalProperties": false
}

POST /api/v1/users

users.create

Pre-provision a console user by email and role. A duplicate email is a 409. Human session only.

Role
owner
Scope
users:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "viewer"
      ]
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "email",
    "role"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "role": {
          "type": "string",
          "enum": [
            "member",
            "viewer",
            "admin",
            "owner"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "invited",
            "active",
            "disabled"
          ]
        },
        "authProvider": {
          "type": "string"
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "lastLoginAt": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "email",
        "name",
        "role",
        "status",
        "authProvider",
        "externalId",
        "createdAt",
        "lastLoginAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "user"
  ],
  "additionalProperties": false
}

PATCH /api/v1/users/{id}

users.update

Change a user's role or status. Nobody changes their own, and the last active owner stays. Human session only.

Role
owner
Scope
users:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "viewer"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "invited",
        "active",
        "disabled"
      ]
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "role": {
      "type": "string",
      "enum": [
        "member",
        "viewer",
        "admin",
        "owner"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "invited",
        "active",
        "disabled"
      ]
    }
  },
  "required": [
    "ok",
    "role",
    "status"
  ],
  "additionalProperties": false
}

POST /api/v1/credentials

credentials.create

Store a provider key in the chassis under a name models reference. Human session only.

Role
owner
Scope
providers:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "provider": {
      "type": "string",
      "minLength": 1
    },
    "apiKey": {
      "type": "string",
      "minLength": 1
    },
    "apiBase": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "provider",
    "apiKey"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PATCH /api/v1/credentials/{name}

credentials.rotate

Replace a provider key in place; every model on it uses the new key from its next request. Human session only.

Role
owner
Scope
providers:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "apiKey"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

DELETE /api/v1/credentials/{name}

credentials.delete

Delete a provider credential and its declared limit. A 409 names the models still using it. Human session only.

Role
owner
Scope
providers:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/credentials/{name}/limit

credentials.limit.set

Declare a provider credential's token and USD ceilings per window; both null clears them. Human session only.

Role
owner
Scope
providers:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limitTokens": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "limitUsd": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "period": {
      "type": "string",
      "enum": [
        "month",
        "30d"
      ]
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "credentialName": {
              "type": "string"
            },
            "limitTokens": {
              "type": [
                "number",
                "null"
              ]
            },
            "limitUsd": {
              "type": [
                "number",
                "null"
              ]
            },
            "period": {
              "type": "string",
              "enum": [
                "month",
                "30d"
              ]
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "credentialName",
            "limitTokens",
            "limitUsd",
            "period",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "limit"
  ],
  "additionalProperties": false
}

POST /api/v1/models

models.create

Add a model to the chassis catalog. It must name an existing provider credential. Human session only.

Role
admin
Scope
config:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "providerModel": {
      "type": "string",
      "minLength": 1
    },
    "credentialName": {
      "default": "",
      "type": "string"
    },
    "apiBase": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "providerModel"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/models/{id}

models.update

Update a console-added model's provider model, credential or endpoint. Seed models are managed in git. Human session only.

Role
admin
Scope
config:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "providerModel": {
      "type": "string",
      "minLength": 1
    },
    "credentialName": {
      "default": "",
      "type": "string"
    },
    "apiBase": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "providerModel"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

DELETE /api/v1/models/{id}

models.delete

Remove a console-added model from the chassis catalog. A 409 names the routes that still use it as model or fallback. Human session only.

Role
admin
Scope
config:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/prices

prices.import

Import the chassis catalog's list prices. Manual rates are never overwritten. Human session only.

Role
admin
Scope
providers:write
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "found": {
      "type": "number"
    },
    "imported": {
      "type": "number"
    },
    "skippedManual": {
      "type": "number"
    }
  },
  "required": [
    "found",
    "imported",
    "skippedManual"
  ],
  "additionalProperties": false
}

PUT /api/v1/prices

prices.set

Set one model's rates by hand (a negotiated price). An absent rate is unknown. Human session only.

Role
admin
Scope
providers:write
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1
    },
    "inputUsdPerMtok": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "outputUsdPerMtok": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "cacheReadUsdPerMtok": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "cacheWriteUsdPerMtok": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "imageUsdPerUnit": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "audioUsdPerSecond": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "characterUsdPerMchar": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "model"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "price": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string"
        },
        "inputUsdPerMtok": {
          "type": [
            "number",
            "null"
          ]
        },
        "outputUsdPerMtok": {
          "type": [
            "number",
            "null"
          ]
        },
        "cacheReadUsdPerMtok": {
          "type": [
            "number",
            "null"
          ]
        },
        "cacheWriteUsdPerMtok": {
          "type": [
            "number",
            "null"
          ]
        },
        "imageUsdPerUnit": {
          "type": [
            "number",
            "null"
          ]
        },
        "audioUsdPerSecond": {
          "type": [
            "number",
            "null"
          ]
        },
        "characterUsdPerMchar": {
          "type": [
            "number",
            "null"
          ]
        },
        "maxInputTokens": {
          "type": [
            "number",
            "null"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "chassis",
            "manual"
          ]
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "model",
        "inputUsdPerMtok",
        "outputUsdPerMtok",
        "cacheReadUsdPerMtok",
        "cacheWriteUsdPerMtok",
        "imageUsdPerUnit",
        "audioUsdPerSecond",
        "characterUsdPerMchar",
        "maxInputTokens",
        "source",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "price"
  ],
  "additionalProperties": false
}

DELETE /api/v1/prices

prices.delete

Remove a model's rates; its requests are then unpriced. Human session only.

Role
admin
Scope
providers:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/model-policy

model-policy.set

Record or withdraw one model's ZDR attestation — a claim an operator makes, audited with its note. Human session only.

Role
admin
Scope
providers:write
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1
    },
    "zdr": {
      "type": "boolean"
    },
    "note": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "model",
    "zdr"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "policy": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string"
        },
        "zdr": {
          "type": "boolean"
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "model",
        "zdr",
        "note",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "policy"
  ],
  "additionalProperties": false
}

DELETE /api/v1/model-policy

model-policy.delete

Drop a model's attestation, returning it to unattested. ZDR-only traffic stops using it. Human session only.

Role
admin
Scope
providers:write
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/servers

tools.servers.list

List the registered MCP and REST servers with every tool, resource and prompt they declare. Never a credential.

Role
viewer
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "serverId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "transport": {
            "type": "string",
            "enum": [
              "http",
              "sse"
            ]
          },
          "authType": {
            "type": "string",
            "enum": [
              "none",
              "api_key",
              "bearer_token",
              "oauth2"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "readOnly": {
                  "type": "boolean"
                },
                "destructive": {
                  "type": "boolean"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "requiredScopes": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "mask": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "rateLimit": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "requests": {
                          "type": "number"
                        },
                        "windowSeconds": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "requests",
                        "windowSeconds"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "requiresApproval": {
                  "type": "boolean"
                },
                "allowedParams": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "rest": {
                  "type": "object",
                  "properties": {
                    "method": {
                      "type": "string",
                      "enum": [
                        "GET",
                        "POST",
                        "PUT",
                        "PATCH",
                        "DELETE"
                      ]
                    },
                    "path": {
                      "type": "string"
                    },
                    "parameters": {
                      "$ref": "#/$defs/__schema0"
                    }
                  },
                  "required": [
                    "method",
                    "path",
                    "parameters"
                  ],
                  "additionalProperties": false
                },
                "policyInvalid": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "readOnly",
                "destructive",
                "description"
              ],
              "additionalProperties": false
            }
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "uri": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "mimeType": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "requiredScopes": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "policyInvalid": {
                  "type": "boolean"
                }
              },
              "required": [
                "uri",
                "name",
                "description",
                "mimeType"
              ],
              "additionalProperties": false
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "requiredScopes": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "policyInvalid": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "description"
              ],
              "additionalProperties": false
            }
          },
          "custody": {
            "type": "string",
            "enum": [
              "service",
              "connection"
            ]
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "audience": {
            "type": [
              "string",
              "null"
            ]
          },
          "maxScopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "header": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "required": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "header",
                "description",
                "required"
              ],
              "additionalProperties": false
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "mcp",
              "rest"
            ]
          },
          "restAuth": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "enum": [
                      "header",
                      "query"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "prefix": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "location",
                  "name",
                  "prefix"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "serverId",
          "name",
          "url",
          "transport",
          "authType",
          "enabled",
          "description",
          "tools",
          "resources",
          "prompts"
        ],
        "additionalProperties": false
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "canonicalName": {
            "type": "string"
          },
          "server": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "readOnly": {
            "type": "boolean"
          },
          "destructive": {
            "type": "boolean"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "canonicalName",
          "server",
          "name",
          "readOnly",
          "destructive",
          "description",
          "enabled"
        ],
        "additionalProperties": false
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string"
          },
          "template": {
            "type": "boolean"
          },
          "server": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "mimeType": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "uri",
          "template",
          "server",
          "name",
          "description",
          "mimeType",
          "enabled"
        ],
        "additionalProperties": false
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "canonicalName": {
            "type": "string"
          },
          "server": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "canonicalName",
          "server",
          "name",
          "description",
          "enabled"
        ],
        "additionalProperties": false
      }
    },
    "restCredentials": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "serverId": {
            "type": "string"
          },
          "generation": {
            "type": "number"
          },
          "updatedAt": {
            "type": "string"
          },
          "updatedByUserId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "serverId",
          "generation",
          "updatedAt",
          "updatedByUserId"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "servers",
    "tools",
    "resources",
    "prompts",
    "restCredentials"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "object",
            "array",
            "string",
            "number",
            "integer",
            "boolean",
            "null"
          ]
        },
        "description": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "visible": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "items": {
          "$ref": "#/$defs/__schema0"
        },
        "enum": {
          "type": "array",
          "items": {}
        },
        "default": {}
      },
      "additionalProperties": {}
    }
  }
}

GET /api/v1/tools/servers/{id}/inspect

tools.servers.inspect

Inspect one registered server from stored facts only: which grants reach it, its recent ledger activity and its name collisions.

Role
viewer
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "http",
            "sse"
          ]
        },
        "authType": {
          "type": "string",
          "enum": [
            "none",
            "api_key",
            "bearer_token",
            "oauth2"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "destructive": {
                "type": "boolean"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "mask": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "rateLimit": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "requests": {
                        "type": "number"
                      },
                      "windowSeconds": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "requests",
                      "windowSeconds"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "requiresApproval": {
                "type": "boolean"
              },
              "allowedParams": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "rest": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "GET",
                      "POST",
                      "PUT",
                      "PATCH",
                      "DELETE"
                    ]
                  },
                  "path": {
                    "type": "string"
                  },
                  "parameters": {
                    "$ref": "#/$defs/__schema0"
                  }
                },
                "required": [
                  "method",
                  "path",
                  "parameters"
                ],
                "additionalProperties": false
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "readOnly",
              "destructive",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "uri": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "mimeType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "uri",
              "name",
              "description",
              "mimeType"
            ],
            "additionalProperties": false
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "custody": {
          "type": "string",
          "enum": [
            "service",
            "connection"
          ]
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "audience": {
          "type": [
            "string",
            "null"
          ]
        },
        "maxScopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "variables": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "header": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "required": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "header",
              "description",
              "required"
            ],
            "additionalProperties": false
          }
        },
        "kind": {
          "type": "string",
          "enum": [
            "mcp",
            "rest"
          ]
        },
        "restAuth": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "enum": [
                    "header",
                    "query"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "prefix": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "location",
                "name",
                "prefix"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "serverId",
        "name",
        "url",
        "transport",
        "authType",
        "enabled",
        "description",
        "tools",
        "resources",
        "prompts"
      ],
      "additionalProperties": false
    },
    "reach": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "key",
              "team"
            ]
          },
          "principalId": {
            "type": "string"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "tools": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "readOnly": {
            "type": "boolean"
          },
          "synced": {
            "type": "boolean"
          },
          "syncError": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "principalId",
          "label",
          "tools",
          "readOnly",
          "synced",
          "syncError"
        ],
        "additionalProperties": false
      }
    },
    "activity": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "calls": {
            "type": "number"
          },
          "dispatched": {
            "type": "number"
          },
          "denied": {
            "type": "number"
          },
          "pending": {
            "type": "number"
          },
          "failed": {
            "type": "number"
          },
          "unknown": {
            "type": "number"
          },
          "costUsd": {
            "type": "number"
          },
          "unpricedCalls": {
            "type": "number"
          },
          "avgLatencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "p95LatencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "group",
          "calls",
          "dispatched",
          "denied",
          "pending",
          "failed",
          "unknown",
          "costUsd",
          "unpricedCalls",
          "avgLatencyMs",
          "p95LatencyMs",
          "subjectName"
        ],
        "additionalProperties": false
      }
    },
    "activityDays": {
      "type": "number"
    },
    "ambiguous": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "server",
    "reach",
    "activity",
    "activityDays",
    "ambiguous"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "object",
            "array",
            "string",
            "number",
            "integer",
            "boolean",
            "null"
          ]
        },
        "description": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "visible": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "items": {
          "$ref": "#/$defs/__schema0"
        },
        "enum": {
          "type": "array",
          "items": {}
        },
        "default": {}
      },
      "additionalProperties": {}
    }
  }
}

GET /api/v1/teams

teams.list

List the teams a key may be put in, each with its tool grant and its member count.

Role
viewer
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "teams": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "teamId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "members": {
            "type": "number"
          },
          "toolAccess": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "servers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "resources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "groups": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "readOnly": {
                    "type": "boolean"
                  },
                  "version": {
                    "type": "number"
                  },
                  "syncedVersion": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "syncedAt": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "syncError": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "none",
                      "drift",
                      "ready"
                    ]
                  }
                },
                "required": [
                  "servers",
                  "tools",
                  "resources",
                  "prompts",
                  "groups",
                  "readOnly",
                  "version",
                  "syncedVersion",
                  "syncedAt",
                  "syncError",
                  "status"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "teamId",
          "name",
          "description",
          "createdAt",
          "updatedAt",
          "members",
          "toolAccess"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "teams"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/groups

tools.groups.list

List the tool groups: named bundles of servers, tools, resources and prompts that a grant may name.

Role
viewer
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groups": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "groupId",
          "name",
          "description",
          "servers",
          "tools",
          "resources",
          "prompts",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "groups"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/virtual-servers

tools.virtual-servers.list

List the virtual servers: named toolsets an agent mounts as one endpoint. A mount only narrows a grant.

Role
viewer
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "virtualServers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "serverId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "servers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "disclosure": {
            "type": "string",
            "enum": [
              "all",
              "progressive"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "serverId",
          "name",
          "description",
          "servers",
          "tools",
          "resources",
          "prompts",
          "groups",
          "disclosure",
          "enabled",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    },
    "gatewayUrl": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "virtualServers",
    "gatewayUrl"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/variables

tools.variables.read

Read a service-account key's server variables (a site, a workspace id), per server that declares them. Never a secret.

Role
admin
Scope
tools:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "serverId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "required": {
                  "type": "boolean"
                },
                "value": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "description",
                "required",
                "value"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "serverId",
          "name",
          "variables"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "servers"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/calls

tools.calls.list

List tool-call ledger rows, newest first: person, tool, decision, outcome, latency and cost, refused calls included. Never arguments or results.

Role
viewer
Scope
logs:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number"
          },
          "ts": {
            "type": "string"
          },
          "requestLogId": {
            "type": [
              "number",
              "null"
            ]
          },
          "keyId": {
            "type": "string"
          },
          "subjectType": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          },
          "subjectId": {
            "type": "string"
          },
          "connectionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "server": {
            "type": "string"
          },
          "primitive": {
            "type": "string",
            "enum": [
              "tool",
              "resource",
              "prompt"
            ]
          },
          "tool": {
            "type": "string"
          },
          "policyVersion": {
            "type": "number"
          },
          "decision": {
            "type": "string",
            "enum": [
              "allowed",
              "denied",
              "approval_pending",
              "approved",
              "rejected"
            ]
          },
          "dispatchedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "outcome": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "ok",
                  "failed",
                  "unknown"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "latencyMs": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "costSource": {
            "type": "string",
            "enum": [
              "chassis",
              "declared",
              "none"
            ]
          },
          "guardFindings": {
            "type": "number"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "mount": {
            "type": [
              "string",
              "null"
            ]
          },
          "skillVersionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "sessionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          },
          "subjectEmail": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "ts",
          "requestLogId",
          "keyId",
          "subjectType",
          "subjectId",
          "connectionId",
          "server",
          "primitive",
          "tool",
          "policyVersion",
          "decision",
          "dispatchedAt",
          "finishedAt",
          "outcome",
          "latencyMs",
          "costUsd",
          "costSource",
          "guardFindings",
          "reason",
          "mount",
          "skillVersionId",
          "sessionId",
          "subjectName",
          "subjectEmail"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "rows"
  ],
  "additionalProperties": false
}

GET /api/v1/connections

connections.list

List every upstream connection: whose it is, the provider, scopes, state and last use. Never a token.

Role
viewer
Scope
connections:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "connections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "connectionId": {
            "type": "string"
          },
          "subjectType": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          },
          "subjectId": {
            "type": "string"
          },
          "subjectLabel": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "providerName": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "reauth_required",
              "revoked"
            ]
          },
          "stateReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "connectionId",
          "subjectType",
          "subjectId",
          "subjectLabel",
          "provider",
          "providerName",
          "audience",
          "scopes",
          "state",
          "stateReason",
          "expiresAt",
          "createdAt",
          "lastUsedAt",
          "revokedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "connections"
  ],
  "additionalProperties": false
}

GET /api/v1/connections/providers

connections.providers.list

List the OAuth providers a person may connect an account at, with their endpoints. Never the client secret.

Role
viewer
Scope
connections:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "authorizationUrl": {
            "type": "string"
          },
          "tokenUrl": {
            "type": "string"
          },
          "revocationUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "clientId": {
            "type": "string"
          },
          "hasSecret": {
            "type": "boolean"
          },
          "audience": {
            "type": "string"
          },
          "defaultScopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "provider",
          "displayName",
          "authorizationUrl",
          "tokenUrl",
          "revocationUrl",
          "clientId",
          "hasSecret",
          "audience",
          "defaultScopes",
          "enabled",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "providers"
  ],
  "additionalProperties": false
}

POST /api/v1/tools/servers

tools.servers.register

Register an MCP or REST server, which makes a third-party system reachable through this gateway. An existing id is a 409. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "serverId": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "mcp",
        "rest"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "transport": {
      "type": "string",
      "enum": [
        "http",
        "sse"
      ]
    },
    "authType": {
      "type": "string",
      "enum": [
        "none",
        "api_key",
        "bearer_token",
        "oauth2"
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "variables": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "custody": {
      "type": "string",
      "enum": [
        "service",
        "connection"
      ]
    },
    "provider": {
      "type": [
        "string",
        "null"
      ]
    },
    "audience": {
      "type": [
        "string",
        "null"
      ]
    },
    "maxScopes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "restAuth": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "credential": {
      "type": [
        "string",
        "null"
      ]
    },
    "clearCredential": {
      "type": "boolean"
    }
  },
  "required": [
    "serverId",
    "name",
    "url",
    "transport",
    "authType"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "http",
            "sse"
          ]
        },
        "authType": {
          "type": "string",
          "enum": [
            "none",
            "api_key",
            "bearer_token",
            "oauth2"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "destructive": {
                "type": "boolean"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "mask": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "rateLimit": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "requests": {
                        "type": "number"
                      },
                      "windowSeconds": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "requests",
                      "windowSeconds"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "requiresApproval": {
                "type": "boolean"
              },
              "allowedParams": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "rest": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "GET",
                      "POST",
                      "PUT",
                      "PATCH",
                      "DELETE"
                    ]
                  },
                  "path": {
                    "type": "string"
                  },
                  "parameters": {
                    "$ref": "#/$defs/__schema0"
                  }
                },
                "required": [
                  "method",
                  "path",
                  "parameters"
                ],
                "additionalProperties": false
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "readOnly",
              "destructive",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "uri": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "mimeType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "uri",
              "name",
              "description",
              "mimeType"
            ],
            "additionalProperties": false
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "custody": {
          "type": "string",
          "enum": [
            "service",
            "connection"
          ]
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "audience": {
          "type": [
            "string",
            "null"
          ]
        },
        "maxScopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "variables": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "header": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "required": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "header",
              "description",
              "required"
            ],
            "additionalProperties": false
          }
        },
        "kind": {
          "type": "string",
          "enum": [
            "mcp",
            "rest"
          ]
        },
        "restAuth": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "enum": [
                    "header",
                    "query"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "prefix": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "location",
                "name",
                "prefix"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "serverId",
        "name",
        "url",
        "transport",
        "authType",
        "enabled",
        "description",
        "tools",
        "resources",
        "prompts"
      ],
      "additionalProperties": false
    },
    "chassis": {
      "type": "object",
      "properties": {
        "synced": {
          "type": "boolean"
        },
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "keys": {
          "type": "object",
          "properties": {
            "synced": {
              "type": "number"
            },
            "failed": {
              "type": "number"
            }
          },
          "required": [
            "synced",
            "failed"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "synced",
        "error",
        "keys"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "server",
    "chassis"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "object",
            "array",
            "string",
            "number",
            "integer",
            "boolean",
            "null"
          ]
        },
        "description": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "visible": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "items": {
          "$ref": "#/$defs/__schema0"
        },
        "enum": {
          "type": "array",
          "items": {}
        },
        "default": {}
      },
      "additionalProperties": {}
    }
  }
}

PUT /api/v1/tools/servers/{id}

tools.servers.update

Edit, disable or enable a registered server; the body is merged onto the stored definition. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "serverId": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "mcp",
        "rest"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "transport": {
      "type": "string",
      "enum": [
        "http",
        "sse"
      ]
    },
    "authType": {
      "type": "string",
      "enum": [
        "none",
        "api_key",
        "bearer_token",
        "oauth2"
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "variables": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "custody": {
      "type": "string",
      "enum": [
        "service",
        "connection"
      ]
    },
    "provider": {
      "type": [
        "string",
        "null"
      ]
    },
    "audience": {
      "type": [
        "string",
        "null"
      ]
    },
    "maxScopes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "restAuth": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "credential": {
      "type": [
        "string",
        "null"
      ]
    },
    "clearCredential": {
      "type": "boolean"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "transport": {
          "type": "string",
          "enum": [
            "http",
            "sse"
          ]
        },
        "authType": {
          "type": "string",
          "enum": [
            "none",
            "api_key",
            "bearer_token",
            "oauth2"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "destructive": {
                "type": "boolean"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "mask": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "rateLimit": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "requests": {
                        "type": "number"
                      },
                      "windowSeconds": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "requests",
                      "windowSeconds"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "requiresApproval": {
                "type": "boolean"
              },
              "allowedParams": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "rest": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "GET",
                      "POST",
                      "PUT",
                      "PATCH",
                      "DELETE"
                    ]
                  },
                  "path": {
                    "type": "string"
                  },
                  "parameters": {
                    "$ref": "#/$defs/__schema0"
                  }
                },
                "required": [
                  "method",
                  "path",
                  "parameters"
                ],
                "additionalProperties": false
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "readOnly",
              "destructive",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "uri": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "mimeType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "uri",
              "name",
              "description",
              "mimeType"
            ],
            "additionalProperties": false
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "policyInvalid": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "custody": {
          "type": "string",
          "enum": [
            "service",
            "connection"
          ]
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "audience": {
          "type": [
            "string",
            "null"
          ]
        },
        "maxScopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "variables": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "header": {
                "type": "string"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "required": {
                "type": "boolean"
              }
            },
            "required": [
              "name",
              "header",
              "description",
              "required"
            ],
            "additionalProperties": false
          }
        },
        "kind": {
          "type": "string",
          "enum": [
            "mcp",
            "rest"
          ]
        },
        "restAuth": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "enum": [
                    "header",
                    "query"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "prefix": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "location",
                "name",
                "prefix"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "serverId",
        "name",
        "url",
        "transport",
        "authType",
        "enabled",
        "description",
        "tools",
        "resources",
        "prompts"
      ],
      "additionalProperties": false
    },
    "chassis": {
      "type": "object",
      "properties": {
        "synced": {
          "type": "boolean"
        },
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "keys": {
          "type": "object",
          "properties": {
            "synced": {
              "type": "number"
            },
            "failed": {
              "type": "number"
            }
          },
          "required": [
            "synced",
            "failed"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "synced",
        "error",
        "keys"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "server",
    "chassis"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "object",
            "array",
            "string",
            "number",
            "integer",
            "boolean",
            "null"
          ]
        },
        "description": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "visible": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "items": {
          "$ref": "#/$defs/__schema0"
        },
        "enum": {
          "type": "array",
          "items": {}
        },
        "default": {}
      },
      "additionalProperties": {}
    }
  }
}

DELETE /api/v1/tools/servers/{id}

tools.servers.delete

Remove a registered server. Grants that name it stay, inert, and revive if the id returns. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "chassis": {
      "type": "object",
      "properties": {
        "synced": {
          "type": "boolean"
        },
        "error": {
          "type": [
            "string",
            "null"
          ]
        },
        "keys": {
          "type": "object",
          "properties": {
            "synced": {
              "type": "number"
            },
            "failed": {
              "type": "number"
            }
          },
          "required": [
            "synced",
            "failed"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "synced",
        "error",
        "keys"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "chassis"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/servers/{id}/discover

tools.servers.discover

List what a registered MCP server offers now, through the chassis WITH THE SERVICE CREDENTIAL, against what it declares. Writes nothing. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "serverId": {
      "type": "string"
    },
    "separator": {
      "type": "string"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "served",
              "undeclared",
              "missing"
            ]
          },
          "offered": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "chassisName": {
                    "type": "string"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "params": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "readOnlyHint": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "destructiveHint": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  }
                },
                "required": [
                  "chassisName",
                  "description",
                  "params",
                  "readOnlyHint",
                  "destructiveHint"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "declaredReadOnly": {
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "status",
          "offered",
          "declaredReadOnly"
        ],
        "additionalProperties": false
      }
    },
    "unprefixed": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "serverId",
    "separator",
    "tools",
    "unprefixed"
  ],
  "additionalProperties": false
}

POST /api/v1/teams

teams.upsert

Create a team a key may be put in, or rename one. Human session only.

Role
admin
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "teamId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "teamId",
    "name"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "team": {
      "type": "object",
      "properties": {
        "teamId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "teamId",
        "name",
        "description",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "team"
  ],
  "additionalProperties": false
}

DELETE /api/v1/teams/{id}

teams.delete

Remove an EMPTY team with its tool grant. A team with member keys is a 409 with the count. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/teams/tools

teams.tools.set

Set a team's tool grant, AND-ed with each member key's own, then push every member key. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "teamId": {
      "type": "string",
      "minLength": 1
    },
    "servers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "readOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "teamId",
    "servers",
    "tools",
    "readOnly"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "access": {
      "type": "object",
      "properties": {
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "readOnly": {
          "type": "boolean"
        },
        "version": {
          "type": "number"
        },
        "syncedVersion": {
          "type": [
            "number",
            "null"
          ]
        },
        "syncedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "syncError": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "drift",
            "ready"
          ]
        }
      },
      "required": [
        "servers",
        "tools",
        "resources",
        "prompts",
        "groups",
        "readOnly",
        "version",
        "syncedVersion",
        "syncedAt",
        "syncError",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "access"
  ],
  "additionalProperties": false
}

POST /api/v1/teams/tools/resync

teams.tools.resync

Push a team's stored grant to every member key again, after a failed sync. Human session only.

Role
admin
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "teamId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "teamId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "access": {
      "type": "object",
      "properties": {
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "readOnly": {
          "type": "boolean"
        },
        "version": {
          "type": "number"
        },
        "syncedVersion": {
          "type": [
            "number",
            "null"
          ]
        },
        "syncedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "syncError": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "drift",
            "ready"
          ]
        }
      },
      "required": [
        "servers",
        "tools",
        "resources",
        "prompts",
        "groups",
        "readOnly",
        "version",
        "syncedVersion",
        "syncedAt",
        "syncError",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "access"
  ],
  "additionalProperties": false
}

DELETE /api/v1/teams/tools

teams.tools.revoke

Remove a team's tool grant: every key in the team then has NO tools. Human session only.

Role
admin
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/tools/groups

tools.groups.upsert

Create or replace a tool group; every grant that names it is bumped and re-pushed in the same request. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "groupId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "servers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "groupId",
    "name"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "group": {
      "type": "object",
      "properties": {
        "groupId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "groupId",
        "name",
        "description",
        "servers",
        "tools",
        "resources",
        "prompts",
        "updatedAt"
      ],
      "additionalProperties": false
    },
    "sync": {
      "type": "object",
      "properties": {
        "synced": {
          "type": "number"
        },
        "failed": {
          "type": "number"
        },
        "affected": {
          "type": "number"
        }
      },
      "required": [
        "synced",
        "failed",
        "affected"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "group",
    "sync"
  ],
  "additionalProperties": false
}

DELETE /api/v1/tools/groups/{id}

tools.groups.delete

Remove a tool group. Grants that name it keep the name, which grants nothing; each is re-pushed. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "sync": {
      "type": "object",
      "properties": {
        "synced": {
          "type": "number"
        },
        "failed": {
          "type": "number"
        },
        "affected": {
          "type": "number"
        }
      },
      "required": [
        "synced",
        "failed",
        "affected"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "sync"
  ],
  "additionalProperties": false
}

POST /api/v1/tools/virtual-servers

tools.virtual-servers.upsert

Create or replace a virtual server: the toolset an agent mounts at /mcp/{serverId}. It only narrows a grant. Human session only.

Role
admin
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "serverId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "servers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "resources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "prompts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "disclosure": {
      "type": "string",
      "enum": [
        "all",
        "progressive"
      ]
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "serverId",
    "name"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "virtualServer": {
      "type": "object",
      "properties": {
        "serverId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "servers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "disclosure": {
          "type": "string",
          "enum": [
            "all",
            "progressive"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "serverId",
        "name",
        "description",
        "servers",
        "tools",
        "resources",
        "prompts",
        "groups",
        "disclosure",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "virtualServer"
  ],
  "additionalProperties": false
}

DELETE /api/v1/tools/virtual-servers/{id}

tools.virtual-servers.delete

Remove a virtual server; its endpoint answers 404 from the gateway's next poll. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/tools/variables

tools.variables.set

Replace a service-account key's variables for one server, which chooses where its calls land. Human session only.

Role
admin
Safe to retry
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "serverId": {
      "type": "string",
      "minLength": 1
    },
    "values": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "keyId",
    "serverId",
    "values"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "serverId": {
      "type": "string"
    },
    "set": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "refused": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "serverId",
    "set",
    "refused"
  ],
  "additionalProperties": false
}

GET /api/v1/tools/approvals

tools.approvals.list

List the tool calls parked for an approval, newest first, with their ARGUMENTS while open. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "toolCallId": {
            "type": "number"
          },
          "keyId": {
            "type": "string"
          },
          "subjectType": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          },
          "subjectId": {
            "type": "string"
          },
          "server": {
            "type": "string"
          },
          "tool": {
            "type": "string"
          },
          "argsHash": {
            "type": "string"
          },
          "arguments": {},
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "consumed",
              "rejected",
              "cancelled",
              "expired"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string"
          },
          "decidedBy": {
            "type": [
              "string",
              "null"
            ]
          },
          "decidedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "consumedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reportedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "subjectName": {
            "type": [
              "string",
              "null"
            ]
          },
          "subjectEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "decidedByName": {
            "type": [
              "string",
              "null"
            ]
          },
          "selfDecided": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "toolCallId",
          "keyId",
          "subjectType",
          "subjectId",
          "server",
          "tool",
          "argsHash",
          "arguments",
          "status",
          "createdAt",
          "expiresAt",
          "decidedBy",
          "decidedAt",
          "consumedAt",
          "reportedAt",
          "subjectName",
          "subjectEmail",
          "decidedByName",
          "selfDecided"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "rows"
  ],
  "additionalProperties": false
}

POST /api/v1/tools/approvals/{id}

tools.approvals.decide

Approve, reject or withdraw one parked tool call. Nothing runs here: the gateway runs the agent's identical retry. A row that already moved is a 409. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "reject",
        "cancel"
      ]
    }
  },
  "required": [
    "decision"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "approval": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "toolCallId": {
          "type": "number"
        },
        "keyId": {
          "type": "string"
        },
        "subjectType": {
          "type": "string",
          "enum": [
            "human",
            "workload"
          ]
        },
        "subjectId": {
          "type": "string"
        },
        "server": {
          "type": "string"
        },
        "tool": {
          "type": "string"
        },
        "argsHash": {
          "type": "string"
        },
        "arguments": {},
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "approved",
            "consumed",
            "rejected",
            "cancelled",
            "expired"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string"
        },
        "decidedBy": {
          "type": [
            "string",
            "null"
          ]
        },
        "decidedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "consumedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reportedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "subjectName": {
          "type": [
            "string",
            "null"
          ]
        },
        "subjectEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "decidedByName": {
          "type": [
            "string",
            "null"
          ]
        },
        "selfDecided": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "toolCallId",
        "keyId",
        "subjectType",
        "subjectId",
        "server",
        "tool",
        "argsHash",
        "arguments",
        "status",
        "createdAt",
        "expiresAt",
        "decidedBy",
        "decidedAt",
        "consumedAt",
        "reportedAt",
        "subjectName",
        "subjectEmail",
        "decidedByName",
        "selfDecided"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "approval"
  ],
  "additionalProperties": false
}

POST /api/v1/connections

connections.start

Start a consent for a service-account key: answers the URL the caller's browser consents at. The gateway completes it. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "minLength": 1
    },
    "keyId": {
      "type": "string",
      "minLength": 1
    },
    "scopes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "string"
        }
      ]
    }
  },
  "required": [
    "provider",
    "keyId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

DELETE /api/v1/connections/{id}

connections.revoke

Revoke any connection locally; the gateway's sweep revokes it upstream. Human session only.

Role
admin
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/connections/providers

connections.providers.create

Register an OAuth provider, its client secret sealed for the gateway. An existing id is a 409. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "provider": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "authorizationUrl": {
      "type": "string"
    },
    "tokenUrl": {
      "type": "string"
    },
    "revocationUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "clientId": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "defaultScopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "clientSecret": {
      "type": "string"
    }
  },
  "required": [
    "provider",
    "displayName",
    "authorizationUrl",
    "tokenUrl",
    "clientId",
    "audience"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

PUT /api/v1/connections/providers/{id}

connections.providers.update

Edit a provider's endpoints, client or secret; the body is merged onto the stored row. A changed audience needs the secret again. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "provider": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "authorizationUrl": {
      "type": "string"
    },
    "tokenUrl": {
      "type": "string"
    },
    "revocationUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "clientId": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "defaultScopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "clientSecret": {
      "type": "string"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

DELETE /api/v1/connections/providers/{id}

connections.providers.delete

Remove an OAuth provider. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/context-packs

packs.list

List the context packs: access policy, published and retired versions with their hashes, assignments and the settings. Never a version's text or a draft.

Role
viewer
Scope
packs:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "packs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "packId": {
            "type": "string"
          },
          "tenant": {
            "type": "string"
          },
          "ownerUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "classification": {
            "type": "string",
            "enum": [
              "public",
              "internal",
              "confidential"
            ]
          },
          "accessPolicy": {
            "type": "object",
            "properties": {
              "keys": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "subjectTypes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "human",
                    "workload"
                  ]
                }
              }
            },
            "required": [
              "keys",
              "subjectTypes"
            ],
            "additionalProperties": false
          },
          "enabled": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "versionId": {
                  "type": "string"
                },
                "seq": {
                  "type": "number"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "draft",
                    "published",
                    "retired"
                  ]
                },
                "hash": {
                  "type": "string"
                },
                "mimeType": {
                  "type": "string"
                },
                "locale": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "publishedAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "retiredAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "versionId",
                "seq",
                "state",
                "hash",
                "mimeType",
                "locale",
                "createdAt",
                "publishedAt",
                "retiredAt"
              ],
              "additionalProperties": false
            }
          },
          "assignments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "assignmentId": {
                  "type": "string"
                },
                "packId": {
                  "type": "string"
                },
                "selectorKind": {
                  "type": "string",
                  "enum": [
                    "any",
                    "key",
                    "user"
                  ]
                },
                "selectorId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "route": {
                  "type": "string"
                },
                "pinnedVersionId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "priority": {
                  "type": "number"
                },
                "budgetTokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "delivery": {
                  "type": "string",
                  "enum": [
                    "whole",
                    "retrieve"
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "assignmentId",
                "packId",
                "selectorKind",
                "selectorId",
                "route",
                "pinnedVersionId",
                "priority",
                "budgetTokens",
                "delivery",
                "enabled",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "packId",
          "tenant",
          "ownerUserId",
          "title",
          "description",
          "classification",
          "accessPolicy",
          "enabled",
          "createdAt",
          "updatedAt",
          "ownerEmail",
          "versions",
          "assignments"
        ],
        "additionalProperties": false
      }
    },
    "settings": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "defaultBudgetTokens": {
          "type": [
            "number",
            "null"
          ]
        },
        "reservedOutputTokens": {
          "type": "number"
        }
      },
      "required": [
        "enabled",
        "defaultBudgetTokens",
        "reservedOutputTokens"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "packs",
    "settings"
  ],
  "additionalProperties": false
}

GET /api/v1/context-packs/{id}/versions

packs.versions.list

Read every version of one pack with its text, drafts and screening records included. A read of company material. Human session only.

Role
viewer
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "versions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "versionId": {
            "type": "string"
          },
          "packId": {
            "type": "string"
          },
          "seq": {
            "type": "number"
          },
          "content": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "hash": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "retired"
            ]
          },
          "createdByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "publishedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "retiredAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewRequestedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewRequestedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "screening": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "screenedAt": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "allow",
                      "flag",
                      "block"
                    ]
                  },
                  "screened": {
                    "type": "boolean"
                  },
                  "routes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "guards": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "coveredBy": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "unavailable": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "guard": {
                          "type": "string"
                        },
                        "category": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "guard",
                        "category"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "findings": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "guard": {
                          "type": "string"
                        },
                        "action": {
                          "type": "string"
                        },
                        "category": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ruleId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ruleType": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "routes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "console",
                            "gateway"
                          ]
                        }
                      },
                      "required": [
                        "guard",
                        "action",
                        "category",
                        "ruleId",
                        "ruleType",
                        "routes",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "gateway": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": false
                          }
                        },
                        "required": [
                          "asked"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": true
                          },
                          "answered": {
                            "type": "boolean",
                            "const": true
                          }
                        },
                        "required": [
                          "asked",
                          "answered"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": true
                          },
                          "answered": {
                            "type": "boolean",
                            "const": false
                          },
                          "error": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "asked",
                          "answered",
                          "error"
                        ],
                        "additionalProperties": false
                      }
                    ]
                  }
                },
                "required": [
                  "screenedAt",
                  "action",
                  "screened",
                  "routes",
                  "guards",
                  "coveredBy",
                  "unavailable",
                  "findings",
                  "gateway"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "createdByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewRequestedByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishedByEmail": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "versionId",
          "packId",
          "seq",
          "content",
          "mimeType",
          "locale",
          "hash",
          "state",
          "createdByUserId",
          "createdAt",
          "publishedByUserId",
          "publishedAt",
          "retiredAt",
          "reviewRequestedByUserId",
          "reviewRequestedAt",
          "screening",
          "createdByEmail",
          "reviewRequestedByEmail",
          "publishedByEmail"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "versions"
  ],
  "additionalProperties": false
}

POST /api/v1/context-packs

packs.create

Create a context pack. It has no version and prepends nothing until one is published. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "packId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "classification": {
      "type": "string",
      "enum": [
        "public",
        "internal",
        "confidential"
      ]
    },
    "accessPolicy": {
      "type": "object",
      "properties": {
        "keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "subjectTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          }
        }
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "ownerUserId": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "packId",
    "title"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pack": {
      "type": "object",
      "properties": {
        "packId": {
          "type": "string"
        },
        "tenant": {
          "type": "string"
        },
        "ownerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "classification": {
          "type": "string",
          "enum": [
            "public",
            "internal",
            "confidential"
          ]
        },
        "accessPolicy": {
          "type": "object",
          "properties": {
            "keys": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subjectTypes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "human",
                  "workload"
                ]
              }
            }
          },
          "required": [
            "keys",
            "subjectTypes"
          ],
          "additionalProperties": false
        },
        "enabled": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "packId",
        "tenant",
        "ownerUserId",
        "title",
        "description",
        "classification",
        "accessPolicy",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "pack"
  ],
  "additionalProperties": false
}

PUT /api/v1/context-packs

packs.settings.update

Change the context-pack settings: the master switch and the two budget numbers. The body is merged onto the stored settings. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "defaultBudgetTokens": {
      "type": [
        "number",
        "null"
      ]
    },
    "reservedOutputTokens": {
      "type": "number"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "settings": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "defaultBudgetTokens": {
          "type": [
            "number",
            "null"
          ]
        },
        "reservedOutputTokens": {
          "type": "number"
        }
      },
      "required": [
        "enabled",
        "defaultBudgetTokens",
        "reservedOutputTokens"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "settings"
  ],
  "additionalProperties": false
}

PUT /api/v1/context-packs/{id}

packs.update

Edit a pack's title, classification, access policy, owner or switch. A PARTIAL body: Disable is one field. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "packId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "classification": {
      "type": "string",
      "enum": [
        "public",
        "internal",
        "confidential"
      ]
    },
    "accessPolicy": {
      "type": "object",
      "properties": {
        "keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "subjectTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          }
        }
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "ownerUserId": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pack": {
      "type": "object",
      "properties": {
        "packId": {
          "type": "string"
        },
        "tenant": {
          "type": "string"
        },
        "ownerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "classification": {
          "type": "string",
          "enum": [
            "public",
            "internal",
            "confidential"
          ]
        },
        "accessPolicy": {
          "type": "object",
          "properties": {
            "keys": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subjectTypes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "human",
                  "workload"
                ]
              }
            }
          },
          "required": [
            "keys",
            "subjectTypes"
          ],
          "additionalProperties": false
        },
        "enabled": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "packId",
        "tenant",
        "ownerUserId",
        "title",
        "description",
        "classification",
        "accessPolicy",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "pack"
  ],
  "additionalProperties": false
}

DELETE /api/v1/context-packs/{id}

packs.delete

Remove a pack with its versions and assignments. Disabling it is the reversible form. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/context-packs/{id}/versions

packs.versions.create

Open a draft version of a pack. A draft is editable and served by nothing. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "content": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "locale": {
      "type": "string"
    }
  },
  "required": [
    "content"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "versionId": {
          "type": "string"
        },
        "packId": {
          "type": "string"
        },
        "seq": {
          "type": "number"
        },
        "content": {
          "type": "string"
        },
        "mimeType": {
          "type": "string"
        },
        "locale": {
          "type": "string"
        },
        "hash": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "draft",
            "published",
            "retired"
          ]
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "publishedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "screening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "screenedAt": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "allow",
                    "flag",
                    "block"
                  ]
                },
                "screened": {
                  "type": "boolean"
                },
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleId": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleType": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "routes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "console",
                          "gateway"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "ruleId",
                      "ruleType",
                      "routes",
                      "source"
                    ],
                    "additionalProperties": false
                  }
                },
                "gateway": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "asked"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "asked",
                        "answered"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": false
                        },
                        "error": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "asked",
                        "answered",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "required": [
                "screenedAt",
                "action",
                "screened",
                "routes",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "gateway"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "versionId",
        "packId",
        "seq",
        "content",
        "mimeType",
        "locale",
        "hash",
        "state",
        "createdByUserId",
        "createdAt",
        "publishedByUserId",
        "publishedAt",
        "retiredAt",
        "reviewRequestedByUserId",
        "reviewRequestedAt",
        "screening"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

PUT /api/v1/context-packs/{id}/versions/{versionId}

packs.versions.update

Edit a draft, ask for its review, publish it (screened first; a block or an unanswered guard refuses) or retire a published version. A published version never changes. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "published",
        "retired"
      ]
    },
    "review": {
      "type": "boolean"
    },
    "content": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "locale": {
      "type": "string"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "versionId": {
          "type": "string"
        },
        "packId": {
          "type": "string"
        },
        "seq": {
          "type": "number"
        },
        "content": {
          "type": "string"
        },
        "mimeType": {
          "type": "string"
        },
        "locale": {
          "type": "string"
        },
        "hash": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "draft",
            "published",
            "retired"
          ]
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "publishedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "screening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "screenedAt": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "allow",
                    "flag",
                    "block"
                  ]
                },
                "screened": {
                  "type": "boolean"
                },
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleId": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleType": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "routes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "console",
                          "gateway"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "ruleId",
                      "ruleType",
                      "routes",
                      "source"
                    ],
                    "additionalProperties": false
                  }
                },
                "gateway": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "asked"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "asked",
                        "answered"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": false
                        },
                        "error": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "asked",
                        "answered",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "required": [
                "screenedAt",
                "action",
                "screened",
                "routes",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "gateway"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "versionId",
        "packId",
        "seq",
        "content",
        "mimeType",
        "locale",
        "hash",
        "state",
        "createdByUserId",
        "createdAt",
        "publishedByUserId",
        "publishedAt",
        "retiredAt",
        "reviewRequestedByUserId",
        "reviewRequestedAt",
        "screening"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

DELETE /api/v1/context-packs/{id}/versions/{versionId}

packs.versions.delete

Delete a draft. A published or retired version is history and stays: retire it instead. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/context-packs/{id}/assignments

packs.assignments.create

Assign a pack to a (selector, route): where it is offered. Who may see it is the pack's own access policy. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "selectorKind": {
      "type": "string",
      "enum": [
        "any",
        "key",
        "user"
      ]
    },
    "selectorId": {
      "type": [
        "string",
        "null"
      ]
    },
    "route": {
      "type": "string"
    },
    "pinnedVersionId": {
      "type": [
        "string",
        "null"
      ]
    },
    "priority": {
      "type": "number"
    },
    "budgetTokens": {
      "type": [
        "number",
        "null"
      ]
    },
    "delivery": {
      "type": "string",
      "enum": [
        "whole",
        "retrieve"
      ]
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "selectorKind",
    "route"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "assignment": {
      "type": "object",
      "properties": {
        "assignmentId": {
          "type": "string"
        },
        "packId": {
          "type": "string"
        },
        "selectorKind": {
          "type": "string",
          "enum": [
            "any",
            "key",
            "user"
          ]
        },
        "selectorId": {
          "type": [
            "string",
            "null"
          ]
        },
        "route": {
          "type": "string"
        },
        "pinnedVersionId": {
          "type": [
            "string",
            "null"
          ]
        },
        "priority": {
          "type": "number"
        },
        "budgetTokens": {
          "type": [
            "number",
            "null"
          ]
        },
        "delivery": {
          "type": "string",
          "enum": [
            "whole",
            "retrieve"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "assignmentId",
        "packId",
        "selectorKind",
        "selectorId",
        "route",
        "pinnedVersionId",
        "priority",
        "budgetTokens",
        "delivery",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "assignment"
  ],
  "additionalProperties": false
}

PUT /api/v1/context-packs/{id}/assignments/{assignmentId}

packs.assignments.update

Edit an assignment in place. A PARTIAL body: Disable is one field. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "selectorKind": {
      "type": "string",
      "enum": [
        "any",
        "key",
        "user"
      ]
    },
    "selectorId": {
      "type": [
        "string",
        "null"
      ]
    },
    "route": {
      "type": "string"
    },
    "pinnedVersionId": {
      "type": [
        "string",
        "null"
      ]
    },
    "priority": {
      "type": "number"
    },
    "budgetTokens": {
      "type": [
        "number",
        "null"
      ]
    },
    "delivery": {
      "type": "string",
      "enum": [
        "whole",
        "retrieve"
      ]
    },
    "enabled": {
      "type": "boolean"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "assignment": {
      "type": "object",
      "properties": {
        "assignmentId": {
          "type": "string"
        },
        "packId": {
          "type": "string"
        },
        "selectorKind": {
          "type": "string",
          "enum": [
            "any",
            "key",
            "user"
          ]
        },
        "selectorId": {
          "type": [
            "string",
            "null"
          ]
        },
        "route": {
          "type": "string"
        },
        "pinnedVersionId": {
          "type": [
            "string",
            "null"
          ]
        },
        "priority": {
          "type": "number"
        },
        "budgetTokens": {
          "type": [
            "number",
            "null"
          ]
        },
        "delivery": {
          "type": "string",
          "enum": [
            "whole",
            "retrieve"
          ]
        },
        "enabled": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "assignmentId",
        "packId",
        "selectorKind",
        "selectorId",
        "route",
        "pinnedVersionId",
        "priority",
        "budgetTokens",
        "delivery",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "assignment"
  ],
  "additionalProperties": false
}

DELETE /api/v1/context-packs/{id}/assignments/{assignmentId}

packs.assignments.delete

Remove an assignment. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/skills

skills.list

List the company skills: who may select each, and every published or retired version's title, digest and declared requirements. Never a procedure's text, a draft or a review comment.

Role
viewer
Scope
skills:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "skillId": {
            "type": "string"
          },
          "tenant": {
            "type": "string"
          },
          "ownerUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "accessPolicy": {
            "type": "object",
            "properties": {
              "keys": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "subjectTypes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "human",
                    "workload"
                  ]
                }
              }
            },
            "required": [
              "keys",
              "subjectTypes"
            ],
            "additionalProperties": false
          },
          "enabled": {
            "type": "boolean"
          },
          "invalid": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "promptName": {
            "type": "string"
          },
          "ownerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "versionId": {
                  "type": "string"
                },
                "seq": {
                  "type": "number"
                },
                "title": {
                  "type": "string"
                },
                "digest": {
                  "type": "string"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "draft",
                    "published",
                    "retired"
                  ]
                },
                "requires": {
                  "type": "object",
                  "properties": {
                    "tools": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "resources": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "prompts": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "tools",
                    "resources",
                    "prompts"
                  ],
                  "additionalProperties": false
                },
                "compatibility": {
                  "type": "object",
                  "properties": {
                    "clients": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "notes": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "clients",
                    "notes"
                  ],
                  "additionalProperties": false
                },
                "reviewed": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "primitive": {
                        "type": "string",
                        "enum": [
                          "tool",
                          "resource",
                          "prompt"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "readOnly": {
                        "type": "boolean"
                      },
                      "requiredScopes": {
                        "anyOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "custody": {
                        "type": "string",
                        "enum": [
                          "service",
                          "connection"
                        ]
                      }
                    },
                    "required": [
                      "primitive",
                      "name",
                      "readOnly",
                      "requiredScopes",
                      "custody"
                    ],
                    "additionalProperties": false
                  }
                },
                "selfReviewed": {
                  "type": "boolean"
                },
                "publishedAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "publishedByEmail": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "retiredAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "invalid": {
                  "type": "boolean"
                }
              },
              "required": [
                "versionId",
                "seq",
                "title",
                "digest",
                "state",
                "requires",
                "compatibility",
                "reviewed",
                "selfReviewed",
                "publishedAt",
                "publishedByEmail",
                "retiredAt"
              ],
              "additionalProperties": false
            }
          },
          "servedVersionId": {
            "type": [
              "string",
              "null"
            ]
          },
          "rollbackVersionId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "skillId",
          "tenant",
          "ownerUserId",
          "accessPolicy",
          "enabled",
          "createdAt",
          "updatedAt",
          "promptName",
          "ownerEmail",
          "versions",
          "servedVersionId",
          "rollbackVersionId"
        ],
        "additionalProperties": false
      }
    },
    "settings": {
      "type": "object",
      "properties": {
        "allowSelfPublish": {
          "type": "boolean"
        }
      },
      "required": [
        "allowSelfPublish"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "skills",
    "settings"
  ],
  "additionalProperties": false
}

GET /api/v1/skills/{id}/versions

skills.versions.list

Read every version of one skill with its procedure, drafts and review comments included. A read of company material. Human session only.

Role
viewer
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "versions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "versionId": {
            "type": "string"
          },
          "skillId": {
            "type": "string"
          },
          "seq": {
            "type": "number"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "requires": {
            "type": "object",
            "properties": {
              "tools": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "resources": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "prompts": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "tools",
              "resources",
              "prompts"
            ],
            "additionalProperties": false
          },
          "compatibility": {
            "type": "object",
            "properties": {
              "clients": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "notes": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "clients",
              "notes"
            ],
            "additionalProperties": false
          },
          "digest": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "retired"
            ]
          },
          "reviewed": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "primitive": {
                  "type": "string",
                  "enum": [
                    "tool",
                    "resource",
                    "prompt"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "readOnly": {
                  "type": "boolean"
                },
                "requiredScopes": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "custody": {
                  "type": "string",
                  "enum": [
                    "service",
                    "connection"
                  ]
                }
              },
              "required": [
                "primitive",
                "name",
                "readOnly",
                "requiredScopes",
                "custody"
              ],
              "additionalProperties": false
            }
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishedByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "invalid": {
            "type": "boolean"
          },
          "createdByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          },
          "lastEditedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "type": "string"
          },
          "reviewRequestedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewRequestedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewDigest": {
            "type": [
              "string",
              "null"
            ]
          },
          "screening": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "screenedAt": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "allow",
                      "flag",
                      "block"
                    ]
                  },
                  "screened": {
                    "type": "boolean"
                  },
                  "routes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "guards": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "coveredBy": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "unavailable": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "guard": {
                          "type": "string"
                        },
                        "category": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "guard",
                        "category"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "findings": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "guard": {
                          "type": "string"
                        },
                        "action": {
                          "type": "string"
                        },
                        "category": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ruleId": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "ruleType": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "routes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "console",
                            "gateway"
                          ]
                        }
                      },
                      "required": [
                        "guard",
                        "action",
                        "category",
                        "ruleId",
                        "ruleType",
                        "routes",
                        "source"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "gateway": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": false
                          }
                        },
                        "required": [
                          "asked"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": true
                          },
                          "answered": {
                            "type": "boolean",
                            "const": true
                          }
                        },
                        "required": [
                          "asked",
                          "answered"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "asked": {
                            "type": "boolean",
                            "const": true
                          },
                          "answered": {
                            "type": "boolean",
                            "const": false
                          },
                          "error": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "asked",
                          "answered",
                          "error"
                        ],
                        "additionalProperties": false
                      }
                    ]
                  }
                },
                "required": [
                  "screenedAt",
                  "action",
                  "screened",
                  "routes",
                  "guards",
                  "coveredBy",
                  "unavailable",
                  "findings",
                  "gateway"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "publishedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "retiredByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "retiredAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewerUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "changesRequestedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "changesRequestedContent": {
            "type": [
              "string",
              "null"
            ]
          },
          "selfReviewed": {
            "type": "boolean"
          },
          "contributorUserIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "lastEditedByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewRequestedByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "reviewerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "retiredByEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "contributorEmails": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "comments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "commentId": {
                  "type": "string"
                },
                "versionId": {
                  "type": "string"
                },
                "digest": {
                  "type": "string"
                },
                "line": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "quote": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "body": {
                  "type": "string"
                },
                "authorUserId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "authorEmail": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "open",
                    "resolved"
                  ]
                },
                "reply": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "resolvedByUserId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "resolvedAt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "createdAt": {
                  "type": "string"
                }
              },
              "required": [
                "commentId",
                "versionId",
                "digest",
                "line",
                "quote",
                "body",
                "authorUserId",
                "authorEmail",
                "state",
                "reply",
                "resolvedByUserId",
                "resolvedAt",
                "createdAt"
              ],
              "additionalProperties": false
            }
          },
          "reviewText": {
            "type": "string"
          },
          "undeclaredMentions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "versionId",
          "skillId",
          "seq",
          "title",
          "description",
          "content",
          "requires",
          "compatibility",
          "digest",
          "state",
          "reviewed",
          "publishedAt",
          "publishedByEmail",
          "createdByUserId",
          "createdAt",
          "lastEditedByUserId",
          "updatedAt",
          "reviewRequestedByUserId",
          "reviewRequestedAt",
          "reviewDigest",
          "screening",
          "publishedByUserId",
          "retiredByUserId",
          "retiredAt",
          "reviewerUserId",
          "changesRequestedAt",
          "changesRequestedContent",
          "selfReviewed",
          "contributorUserIds",
          "createdByEmail",
          "lastEditedByEmail",
          "reviewRequestedByEmail",
          "reviewerEmail",
          "retiredByEmail",
          "contributorEmails",
          "comments",
          "reviewText",
          "undeclaredMentions"
        ],
        "additionalProperties": false
      }
    },
    "choices": {
      "type": "object",
      "properties": {
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "tools",
        "resources",
        "prompts"
      ],
      "additionalProperties": false
    },
    "reviewers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "email",
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "versions",
    "choices",
    "reviewers"
  ],
  "additionalProperties": false
}

POST /api/v1/skills

skills.create

Create a skill. It has no version and is selectable by nobody until one is published. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "skillId": {
      "type": "string"
    },
    "accessPolicy": {
      "type": "object",
      "properties": {
        "keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "subjectTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          }
        }
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "ownerUserId": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "skillId"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "skill": {
      "type": "object",
      "properties": {
        "skillId": {
          "type": "string"
        },
        "tenant": {
          "type": "string"
        },
        "ownerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "accessPolicy": {
          "type": "object",
          "properties": {
            "keys": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subjectTypes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "human",
                  "workload"
                ]
              }
            }
          },
          "required": [
            "keys",
            "subjectTypes"
          ],
          "additionalProperties": false
        },
        "enabled": {
          "type": "boolean"
        },
        "invalid": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "skillId",
        "tenant",
        "ownerUserId",
        "accessPolicy",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "skill"
  ],
  "additionalProperties": false
}

PUT /api/v1/skills

skills.settings.update

Set the owner's switch: whether an admin may publish their own skill without a second reviewer. Owner only. Human session only.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "allowSelfPublish": {
      "type": "boolean"
    }
  },
  "required": [
    "allowSelfPublish"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "settings": {
      "type": "object",
      "properties": {
        "allowSelfPublish": {
          "type": "boolean"
        }
      },
      "required": [
        "allowSelfPublish"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "settings"
  ],
  "additionalProperties": false
}

PUT /api/v1/skills/{id}

skills.update

Edit who may select a skill, whether it is on, or who owns it. A PARTIAL body; no review, because none of it is text an agent reads. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accessPolicy": {
      "type": "object",
      "properties": {
        "keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "subjectTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "human",
              "workload"
            ]
          }
        }
      }
    },
    "enabled": {
      "type": "boolean"
    },
    "ownerUserId": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "skill": {
      "type": "object",
      "properties": {
        "skillId": {
          "type": "string"
        },
        "tenant": {
          "type": "string"
        },
        "ownerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "accessPolicy": {
          "type": "object",
          "properties": {
            "keys": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subjectTypes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "human",
                  "workload"
                ]
              }
            }
          },
          "required": [
            "keys",
            "subjectTypes"
          ],
          "additionalProperties": false
        },
        "enabled": {
          "type": "boolean"
        },
        "invalid": {
          "type": "boolean"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "skillId",
        "tenant",
        "ownerUserId",
        "accessPolicy",
        "enabled",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "skill"
  ],
  "additionalProperties": false
}

DELETE /api/v1/skills/{id}

skills.delete

Remove a skill with no published or retired version. One with history is named by the tool-call ledger: disable it instead (409). Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/skills/{id}/versions

skills.versions.create

Open a draft version of a skill, from fields or from an earlier version's text. The opener is its author and may not approve it. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fromVersionId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "requires": {
      "type": "object",
      "properties": {
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "compatibility": {
      "type": "object",
      "properties": {
        "clients": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "versionId": {
          "type": "string"
        },
        "skillId": {
          "type": "string"
        },
        "seq": {
          "type": "number"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "content": {
          "type": "string"
        },
        "requires": {
          "type": "object",
          "properties": {
            "tools": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "prompts": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "tools",
            "resources",
            "prompts"
          ],
          "additionalProperties": false
        },
        "compatibility": {
          "type": "object",
          "properties": {
            "clients": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "notes": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "clients",
            "notes"
          ],
          "additionalProperties": false
        },
        "digest": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "draft",
            "published",
            "retired"
          ]
        },
        "reviewed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "primitive": {
                "type": "string",
                "enum": [
                  "tool",
                  "resource",
                  "prompt"
                ]
              },
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "custody": {
                "type": "string",
                "enum": [
                  "service",
                  "connection"
                ]
              }
            },
            "required": [
              "primitive",
              "name",
              "readOnly",
              "requiredScopes",
              "custody"
            ],
            "additionalProperties": false
          }
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "publishedByEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "invalid": {
          "type": "boolean"
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "lastEditedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "updatedAt": {
          "type": "string"
        },
        "reviewRequestedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewDigest": {
          "type": [
            "string",
            "null"
          ]
        },
        "screening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "screenedAt": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "allow",
                    "flag",
                    "block"
                  ]
                },
                "screened": {
                  "type": "boolean"
                },
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleId": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleType": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "routes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "console",
                          "gateway"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "ruleId",
                      "ruleType",
                      "routes",
                      "source"
                    ],
                    "additionalProperties": false
                  }
                },
                "gateway": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "asked"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "asked",
                        "answered"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": false
                        },
                        "error": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "asked",
                        "answered",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "required": [
                "screenedAt",
                "action",
                "screened",
                "routes",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "gateway"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "publishedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedContent": {
          "type": [
            "string",
            "null"
          ]
        },
        "selfReviewed": {
          "type": "boolean"
        },
        "contributorUserIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "versionId",
        "skillId",
        "seq",
        "title",
        "description",
        "content",
        "requires",
        "compatibility",
        "digest",
        "state",
        "reviewed",
        "publishedAt",
        "publishedByEmail",
        "createdByUserId",
        "createdAt",
        "lastEditedByUserId",
        "updatedAt",
        "reviewRequestedByUserId",
        "reviewRequestedAt",
        "reviewDigest",
        "screening",
        "publishedByUserId",
        "retiredByUserId",
        "retiredAt",
        "reviewerUserId",
        "changesRequestedAt",
        "changesRequestedContent",
        "selfReviewed",
        "contributorUserIds"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

PUT /api/v1/skills/{id}/versions/{versionId}

skills.versions.update

Edit a draft, name its reviewer or withdraw the review, self-publish it under the owner's switch (screened), or retire a published version. Human session only.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "published",
        "retired"
      ]
    },
    "mode": {
      "type": "string"
    },
    "expectedDigest": {
      "type": "string"
    },
    "review": {
      "type": "boolean"
    },
    "reviewerUserId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "requires": {
      "type": "object",
      "properties": {
        "tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prompts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "compatibility": {
      "type": "object",
      "properties": {
        "clients": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "versionId": {
          "type": "string"
        },
        "skillId": {
          "type": "string"
        },
        "seq": {
          "type": "number"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "content": {
          "type": "string"
        },
        "requires": {
          "type": "object",
          "properties": {
            "tools": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "prompts": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "tools",
            "resources",
            "prompts"
          ],
          "additionalProperties": false
        },
        "compatibility": {
          "type": "object",
          "properties": {
            "clients": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "notes": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "clients",
            "notes"
          ],
          "additionalProperties": false
        },
        "digest": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "draft",
            "published",
            "retired"
          ]
        },
        "reviewed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "primitive": {
                "type": "string",
                "enum": [
                  "tool",
                  "resource",
                  "prompt"
                ]
              },
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "custody": {
                "type": "string",
                "enum": [
                  "service",
                  "connection"
                ]
              }
            },
            "required": [
              "primitive",
              "name",
              "readOnly",
              "requiredScopes",
              "custody"
            ],
            "additionalProperties": false
          }
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "publishedByEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "invalid": {
          "type": "boolean"
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "lastEditedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "updatedAt": {
          "type": "string"
        },
        "reviewRequestedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewDigest": {
          "type": [
            "string",
            "null"
          ]
        },
        "screening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "screenedAt": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "allow",
                    "flag",
                    "block"
                  ]
                },
                "screened": {
                  "type": "boolean"
                },
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleId": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleType": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "routes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "console",
                          "gateway"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "ruleId",
                      "ruleType",
                      "routes",
                      "source"
                    ],
                    "additionalProperties": false
                  }
                },
                "gateway": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "asked"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "asked",
                        "answered"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": false
                        },
                        "error": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "asked",
                        "answered",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "required": [
                "screenedAt",
                "action",
                "screened",
                "routes",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "gateway"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "publishedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedContent": {
          "type": [
            "string",
            "null"
          ]
        },
        "selfReviewed": {
          "type": "boolean"
        },
        "contributorUserIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "versionId",
        "skillId",
        "seq",
        "title",
        "description",
        "content",
        "requires",
        "compatibility",
        "digest",
        "state",
        "reviewed",
        "publishedAt",
        "publishedByEmail",
        "createdByUserId",
        "createdAt",
        "lastEditedByUserId",
        "updatedAt",
        "reviewRequestedByUserId",
        "reviewRequestedAt",
        "reviewDigest",
        "screening",
        "publishedByUserId",
        "retiredByUserId",
        "retiredAt",
        "reviewerUserId",
        "changesRequestedAt",
        "changesRequestedContent",
        "selfReviewed",
        "contributorUserIds"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

DELETE /api/v1/skills/{id}/versions/{versionId}

skills.versions.delete

Delete a draft and its comments. A published or retired version is history and stays. Human session only.

Role
admin
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/skills/{id}/versions/{versionId}/review

skills.versions.review

The named reviewer approves a draft (which publishes it, screened) or sends it back with comments. Only THE reviewer, never a contributor. Human session only.

Role
viewer
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "approve",
        "requestChanges"
      ]
    },
    "expectedDigest": {
      "type": "string"
    },
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "line": {
            "type": [
              "number",
              "null"
            ]
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "body"
        ]
      }
    }
  },
  "required": [
    "action"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "versionId": {
          "type": "string"
        },
        "skillId": {
          "type": "string"
        },
        "seq": {
          "type": "number"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "content": {
          "type": "string"
        },
        "requires": {
          "type": "object",
          "properties": {
            "tools": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "prompts": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "tools",
            "resources",
            "prompts"
          ],
          "additionalProperties": false
        },
        "compatibility": {
          "type": "object",
          "properties": {
            "clients": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "notes": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "clients",
            "notes"
          ],
          "additionalProperties": false
        },
        "digest": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "draft",
            "published",
            "retired"
          ]
        },
        "reviewed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "primitive": {
                "type": "string",
                "enum": [
                  "tool",
                  "resource",
                  "prompt"
                ]
              },
              "name": {
                "type": "string"
              },
              "readOnly": {
                "type": "boolean"
              },
              "requiredScopes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "custody": {
                "type": "string",
                "enum": [
                  "service",
                  "connection"
                ]
              }
            },
            "required": [
              "primitive",
              "name",
              "readOnly",
              "requiredScopes",
              "custody"
            ],
            "additionalProperties": false
          }
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "publishedByEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "invalid": {
          "type": "boolean"
        },
        "createdByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        },
        "lastEditedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "updatedAt": {
          "type": "string"
        },
        "reviewRequestedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewDigest": {
          "type": [
            "string",
            "null"
          ]
        },
        "screening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "screenedAt": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "allow",
                    "flag",
                    "block"
                  ]
                },
                "screened": {
                  "type": "boolean"
                },
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleId": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "ruleType": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "routes": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "console",
                          "gateway"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "ruleId",
                      "ruleType",
                      "routes",
                      "source"
                    ],
                    "additionalProperties": false
                  }
                },
                "gateway": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "asked"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "asked",
                        "answered"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "boolean",
                          "const": true
                        },
                        "answered": {
                          "type": "boolean",
                          "const": false
                        },
                        "error": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "asked",
                        "answered",
                        "error"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "required": [
                "screenedAt",
                "action",
                "screened",
                "routes",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "gateway"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "publishedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "retiredAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewerUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "changesRequestedContent": {
          "type": [
            "string",
            "null"
          ]
        },
        "selfReviewed": {
          "type": "boolean"
        },
        "contributorUserIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "versionId",
        "skillId",
        "seq",
        "title",
        "description",
        "content",
        "requires",
        "compatibility",
        "digest",
        "state",
        "reviewed",
        "publishedAt",
        "publishedByEmail",
        "createdByUserId",
        "createdAt",
        "lastEditedByUserId",
        "updatedAt",
        "reviewRequestedByUserId",
        "reviewRequestedAt",
        "reviewDigest",
        "screening",
        "publishedByUserId",
        "retiredByUserId",
        "retiredAt",
        "reviewerUserId",
        "changesRequestedAt",
        "changesRequestedContent",
        "selfReviewed",
        "contributorUserIds"
      ],
      "additionalProperties": false
    },
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "commentId": {
            "type": "string"
          },
          "versionId": {
            "type": "string"
          },
          "digest": {
            "type": "string"
          },
          "line": {
            "type": [
              "number",
              "null"
            ]
          },
          "quote": {
            "type": [
              "string",
              "null"
            ]
          },
          "body": {
            "type": "string"
          },
          "authorUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "authorEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "open",
              "resolved"
            ]
          },
          "reply": {
            "type": [
              "string",
              "null"
            ]
          },
          "resolvedByUserId": {
            "type": [
              "string",
              "null"
            ]
          },
          "resolvedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string"
          }
        },
        "required": [
          "commentId",
          "versionId",
          "digest",
          "line",
          "quote",
          "body",
          "authorUserId",
          "authorEmail",
          "state",
          "reply",
          "resolvedByUserId",
          "resolvedAt",
          "createdAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

PUT /api/v1/skills/{id}/versions/{versionId}/comments/{commentId}

skills.comments.resolve

Resolve a review comment on a draft, with an optional reply. Only the draft's authors or the comment's writer. Resolving is never approval. Human session only.

Role
viewer
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reply": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "comment": {
      "type": "object",
      "properties": {
        "commentId": {
          "type": "string"
        },
        "versionId": {
          "type": "string"
        },
        "digest": {
          "type": "string"
        },
        "line": {
          "type": [
            "number",
            "null"
          ]
        },
        "quote": {
          "type": [
            "string",
            "null"
          ]
        },
        "body": {
          "type": "string"
        },
        "authorUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "authorEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": "string",
          "enum": [
            "open",
            "resolved"
          ]
        },
        "reply": {
          "type": [
            "string",
            "null"
          ]
        },
        "resolvedByUserId": {
          "type": [
            "string",
            "null"
          ]
        },
        "resolvedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "type": "string"
        }
      },
      "required": [
        "commentId",
        "versionId",
        "digest",
        "line",
        "quote",
        "body",
        "authorUserId",
        "authorEmail",
        "state",
        "reply",
        "resolvedByUserId",
        "resolvedAt",
        "createdAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "comment"
  ],
  "additionalProperties": false
}

GET /api/v1/alerts/channels

alerts.channels.list

List the budget alert channels. A webhook target is masked; the URL is a secret.

Role
owner
Scope
alerts:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "webhook",
              "email"
            ]
          },
          "target": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "minLevel": {
            "type": "number"
          },
          "createdAt": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "target",
          "enabled",
          "minLevel",
          "createdAt"
        ],
        "additionalProperties": false
      }
    },
    "emailConfigured": {
      "type": "boolean"
    }
  },
  "required": [
    "channels",
    "emailConfigured"
  ],
  "additionalProperties": false
}

POST /api/v1/alerts/channels

alerts.channels.create

Add a budget alert channel: a webhook or email recipients, at the 80% or 100% band.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "webhook",
        "email"
      ]
    },
    "target": {
      "type": "string",
      "minLength": 1
    },
    "minLevel": {
      "default": 80,
      "anyOf": [
        {
          "type": "number",
          "const": 80
        },
        {
          "type": "number",
          "const": 100
        }
      ]
    },
    "enabled": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "type",
    "target"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channel": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "webhook",
            "email"
          ]
        },
        "target": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        },
        "minLevel": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "target",
        "enabled",
        "minLevel",
        "createdAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "channel"
  ],
  "additionalProperties": false
}

PATCH /api/v1/alerts/channels/{id}

alerts.channels.update

Enable, disable, re-level or retarget one alert channel. 404 for an unknown channel.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "minLevel": {
      "anyOf": [
        {
          "type": "number",
          "const": 80
        },
        {
          "type": "number",
          "const": 100
        }
      ]
    },
    "target": {
      "type": "string",
      "minLength": 1
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channel": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "webhook",
            "email"
          ]
        },
        "target": {
          "type": "string"
        },
        "enabled": {
          "type": "boolean"
        },
        "minLevel": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "target",
        "enabled",
        "minLevel",
        "createdAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "channel"
  ],
  "additionalProperties": false
}

DELETE /api/v1/alerts/channels/{id}

alerts.channels.delete

Delete one alert channel. Deleting an absent channel succeeds.

Role
owner
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/alerts/check

alerts.check

Evaluate every budget against the alert bands now, and deliver each new crossing once. Safe to repeat.

Role
admin
Scope
alerts:write
Safe to retry
✓
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channels": {
      "type": "number"
    },
    "subjects": {
      "type": "number"
    },
    "fired": {
      "type": "number"
    },
    "deliveries": {
      "type": "number"
    },
    "failures": {
      "type": "number"
    }
  },
  "required": [
    "channels",
    "subjects",
    "fired",
    "deliveries",
    "failures"
  ],
  "additionalProperties": false
}

GET /api/v1/reports/{id}

reports.read

Read one report's definition: a built-in id, or a saved report's uuid the caller may see. The question, never the figures.

Role
viewer
Scope
usage:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "report": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "built_in",
            "saved"
          ]
        },
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "spec": {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "enum": [
                "requests",
                "tool_calls",
                "agent_metrics",
                "outcomes"
              ]
            },
            "dimensions": {
              "maxItems": 2,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              }
            },
            "measures": {
              "minItems": 1,
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "requests",
                  "input_tokens",
                  "output_tokens",
                  "total_tokens",
                  "cached_tokens",
                  "cost_usd",
                  "unpriced_requests",
                  "users",
                  "sessions",
                  "active_hours",
                  "latency_avg_ms",
                  "latency_p95_ms",
                  "ttft_avg_ms",
                  "cost_share",
                  "request_share",
                  "cost_per_user",
                  "requests_per_user",
                  "cost_per_1k_requests",
                  "tokens_per_request",
                  "cost_per_1m_tokens",
                  "cost_per_1k_sessions",
                  "cost_per_active_hour",
                  "cache_hit_rate",
                  "cost_decomposition",
                  "calls",
                  "ok",
                  "failed",
                  "unknown",
                  "denied",
                  "pending",
                  "unpriced_calls",
                  "cost_per_ok_call",
                  "operations",
                  "estimated_cost_usd",
                  "merged_prs",
                  "reverted_prs",
                  "revert_rate",
                  "reviews",
                  "joined_prs",
                  "cost_per_merged_pr"
                ]
              }
            },
            "filters": {
              "type": "object",
              "propertyNames": {
                "type": "string",
                "enum": [
                  "client",
                  "model",
                  "route",
                  "subject",
                  "key",
                  "channel",
                  "tag",
                  "session",
                  "server",
                  "tool",
                  "repository",
                  "day",
                  "week",
                  "month"
                ]
              },
              "additionalProperties": {
                "maxItems": 50,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                }
              }
            },
            "range": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "7d",
                    "30d",
                    "mtd",
                    "last_month"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "compare": {
              "type": "string",
              "enum": [
                "none",
                "previous_period"
              ]
            },
            "view": {
              "type": "string",
              "enum": [
                "table",
                "bar",
                "line",
                "stacked",
                "waterfall"
              ]
            }
          },
          "required": [
            "source",
            "dimensions",
            "measures",
            "filters",
            "range",
            "compare",
            "view"
          ],
          "additionalProperties": false
        },
        "ownerEmail": {
          "type": [
            "string",
            "null"
          ]
        },
        "visibility": {
          "type": "string",
          "enum": [
            "private",
            "role:viewer",
            "role:admin",
            "role:owner"
          ]
        },
        "pinned": {
          "type": "boolean"
        },
        "editable": {
          "type": "boolean"
        },
        "updatedAt": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "kind",
        "id",
        "title",
        "description",
        "spec",
        "ownerEmail",
        "visibility",
        "pinned",
        "editable",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "report"
  ],
  "additionalProperties": false
}

DELETE /api/v1/reports/{id}

reports.delete

Delete a saved report the caller owns. Another person's report, or none, is 404.

Role
viewer
Scope
reports:write
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/config/routes/{name}/utterances

config.utterances.read

Read one route's classifier examples. 404 for an unknown route.

Role
viewer
Scope
config:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "utterances": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "utterances"
  ],
  "additionalProperties": false
}

PUT /api/v1/config/routes/{name}/utterances

config.utterances.set

Replace one route's classifier examples. The gateway rebuilds its embedding index. 404 for an unknown route.

Role
admin
Scope
config:write
Needs If-Match
✓
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "utterances": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "utterances"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "utterances": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ok",
    "utterances"
  ],
  "additionalProperties": false
}

POST /api/v1/capture/plaintext/purge

capture.plaintext.purge

Delete the captured bodies stored before encryption. Their request metadata stays. Irreversible; `dryRun` counts only.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dryRun": {
      "default": false,
      "type": "boolean"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dryRun": {
      "type": "boolean"
    },
    "rows": {
      "type": "number"
    },
    "deleted": {
      "type": "number"
    },
    "remaining": {
      "type": "number"
    }
  },
  "required": [
    "dryRun",
    "rows",
    "deleted",
    "remaining"
  ],
  "additionalProperties": false
}

GET /api/v1/guardrails

guardrails.read

Read the screening rules: the master switch, every rule with its scope and mode, soft-deny and stream screening.

Role
viewer
Scope
guardrails:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "guardrails": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "stages": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "request",
                    "response",
                    "tool_call",
                    "tool_result"
                  ]
                }
              },
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "flag",
                  "block",
                  "escalate"
                ]
              },
              "routes": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "keys": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tags": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "routeModes": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {
                      "type": "string",
                      "enum": [
                        "off",
                        "flag",
                        "block",
                        "escalate"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "keyModes": {
                "anyOf": [
                  {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {
                      "type": "string",
                      "enum": [
                        "off",
                        "flag",
                        "block",
                        "escalate"
                      ]
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "after": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "patterns": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "pattern": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "pattern"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "entropy": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "threshold": {
                        "type": "number"
                      },
                      "minLength": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "enabled",
                      "threshold",
                      "minLength"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "normalizePersian": {
                "type": "boolean"
              },
              "model": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "categories": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "failClosed": {
                "type": "boolean"
              },
              "threshold": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "name",
              "type",
              "stages",
              "mode"
            ],
            "additionalProperties": false
          }
        },
        "softDeny": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "routes",
                "keys",
                "message"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "streamScreening": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "routes": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "maxBytes": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "maxMs": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "onExceeded": {
                  "type": "string",
                  "enum": [
                    "open",
                    "closed"
                  ]
                }
              },
              "required": [
                "routes",
                "keys",
                "maxBytes",
                "maxMs",
                "onExceeded"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "enabled",
        "rules"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "guardrails"
  ],
  "additionalProperties": false
}

PUT /api/v1/guardrails

guardrails.update

Replace the screening rules. The gateway hot-reloads them. A rule that cannot run is refused, never trimmed.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "softDeny": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "streamScreening": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "enabled",
    "rules"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

GET /api/v1/guardrails/activity

guardrails.activity

Count the requests each guardrail rule acted on, per stage and action, over a window (default: 30 days).

Role
viewer
Scope
guardrails:activity:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ruleId": {
            "type": [
              "string",
              "null"
            ]
          },
          "guard": {
            "type": "string"
          },
          "ruleType": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "requests": {
            "type": "number"
          },
          "lastSeen": {
            "type": "string"
          }
        },
        "required": [
          "ruleId",
          "guard",
          "ruleType",
          "stage",
          "action",
          "requests",
          "lastSeen"
        ],
        "additionalProperties": false
      }
    },
    "days": {
      "type": "number"
    }
  },
  "required": [
    "rows",
    "days"
  ],
  "additionalProperties": false
}

POST /api/v1/guardrails/test

guardrails.test

Screen a sample against the rules for a route, key and tags, storing nothing. Budgeted per caller (429); each trial is audited without its text.

Role
admin
Scope
guardrails:test
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "text": {
      "type": "string"
    },
    "stage": {
      "default": "request",
      "type": "string",
      "enum": [
        "request",
        "response"
      ]
    },
    "route": {
      "type": "string",
      "minLength": 1
    },
    "key": {
      "default": "",
      "type": "string"
    },
    "tags": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "text",
    "route"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string"
    },
    "stage": {
      "type": "string",
      "enum": [
        "request",
        "response"
      ]
    },
    "route": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "screensRemaining": {
      "type": "number"
    },
    "guards": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "coveredBy": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "unavailable": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "guard": {
            "type": "string"
          },
          "category": {
            "type": "string"
          }
        },
        "required": [
          "guard",
          "category"
        ],
        "additionalProperties": false
      }
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "guard": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "guard",
          "action",
          "category",
          "reason"
        ],
        "additionalProperties": false
      }
    },
    "remote": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "guard": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "guard",
          "type"
        ],
        "additionalProperties": false
      }
    },
    "gateway": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string"
                },
                "screened": {
                  "type": "boolean"
                },
                "guards": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "coveredBy": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "unavailable": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "guard",
                      "category"
                    ],
                    "additionalProperties": false
                  }
                },
                "findings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "action": {
                        "type": "string"
                      },
                      "category": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "reason": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "action",
                      "category",
                      "reason"
                    ],
                    "additionalProperties": false
                  }
                },
                "keyId": {
                  "type": "string"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "keyMismatch": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "guard": {
                        "type": "string"
                      },
                      "previewed": {
                        "type": "string",
                        "enum": [
                          "off",
                          "flag",
                          "block",
                          "escalate"
                        ]
                      },
                      "actual": {
                        "type": "string",
                        "enum": [
                          "off",
                          "flag",
                          "block",
                          "escalate"
                        ]
                      }
                    },
                    "required": [
                      "guard",
                      "previewed",
                      "actual"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "action",
                "screened",
                "guards",
                "coveredBy",
                "unavailable",
                "findings",
                "keyId",
                "tags",
                "keyMismatch"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              },
              "required": [
                "error"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "softDeny": {
      "type": "boolean"
    }
  },
  "required": [
    "action",
    "stage",
    "route",
    "key",
    "tags",
    "screensRemaining",
    "guards",
    "coveredBy",
    "unavailable",
    "findings",
    "remote",
    "gateway",
    "softDeny"
  ],
  "additionalProperties": false
}

GET /api/v1/retention

retention.read

Read the retention policy (days kept per table; 0 = forever) and the last purge pass.

Role
viewer
Scope
retention:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "retention": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "manualEnabled": {
          "type": "boolean"
        },
        "schedule": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "intervalMinutes": {
              "type": "number"
            },
            "pausedUntil": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "enabled",
            "intervalMinutes",
            "pausedUntil"
          ],
          "additionalProperties": false
        },
        "rules": {
          "type": "object",
          "properties": {
            "request_payloads": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "request_logs": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "otel_metric_points": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "hook_events": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "tool_calls": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "idempotency_keys": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "rate_limit_buckets": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            },
            "copilot_actions": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "days": {
                  "type": "number"
                }
              },
              "required": [
                "enabled",
                "days"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "request_payloads",
            "request_logs",
            "otel_metric_points",
            "hook_events",
            "tool_calls",
            "idempotency_keys",
            "rate_limit_buckets",
            "copilot_actions"
          ],
          "additionalProperties": false
        },
        "batchSize": {
          "type": "number"
        }
      },
      "required": [
        "enabled",
        "manualEnabled",
        "schedule",
        "rules",
        "batchSize"
      ],
      "additionalProperties": false
    },
    "lastRun": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "job": {
              "type": "string"
            },
            "leaseUntil": {
              "type": [
                "string",
                "null"
              ]
            },
            "lastStartedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "lastFinishedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "lastStatus": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "ok",
                    "partial",
                    "failed"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "lastDetail": {
              "type": [
                "string",
                "null"
              ]
            },
            "lastCounts": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "number"
              }
            }
          },
          "required": [
            "job",
            "leaseUntil",
            "lastStartedAt",
            "lastFinishedAt",
            "lastStatus",
            "lastDetail",
            "lastCounts"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "retention",
    "lastRun"
  ],
  "additionalProperties": false
}

PUT /api/v1/retention

retention.update

Replace the retention policy. Owner only; audited before and after.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "manualEnabled": {
      "type": "boolean"
    },
    "schedule": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "rules": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "batchSize": {
      "type": "number"
    }
  },
  "required": [
    "enabled",
    "manualEnabled",
    "schedule",
    "rules"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

POST /api/v1/retention/run

retention.run

Run a purge pass under the current policy now, or count one (`dryRun`). Irreversible. 409 when the policy blocks a manual run.

Role
admin
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dryRun": {
      "default": false,
      "type": "boolean"
    }
  }
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "dryRun": {
      "type": "boolean"
    },
    "blocked": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ok",
        "partial",
        "failed"
      ]
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string"
          },
          "rows": {
            "type": "number"
          },
          "skipped": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "required": [
          "target",
          "rows",
          "skipped",
          "error",
          "truncated"
        ],
        "additionalProperties": false
      }
    },
    "rows": {
      "type": "number"
    }
  },
  "required": [
    "dryRun",
    "blocked",
    "status",
    "targets",
    "rows"
  ],
  "additionalProperties": false
}

GET /api/v1/subscription-lane

subscription-lane.read

Read whether a claude.ai subscription credential may cross the gateway, and what each mode does.

Role
viewer
Scope
subscription_lane:read
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subscriptionLane": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "off",
            "allow",
            "require_key"
          ]
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    },
    "reason": {
      "type": "string"
    },
    "modes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "off",
              "allow",
              "require_key"
            ]
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "mode",
          "reason"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "subscriptionLane",
    "reason",
    "modes"
  ],
  "additionalProperties": false
}

PUT /api/v1/subscription-lane

subscription-lane.update

Set the subscription lane: off, allow, or require_key. Owner only; the gateway applies it on its next config poll.

Role
owner
Request body
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "off",
        "allow",
        "require_key"
      ]
    }
  },
  "required": [
    "mode"
  ]
}
Response
json schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "subscriptionLane": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "off",
            "allow",
            "require_key"
          ]
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "ok",
    "subscriptionLane"
  ],
  "additionalProperties": false
}