Metadata-Version: 2.5
Name: smart-agenthub
Version: 0.1.1
Summary: Python SDK and CLI for Agent Hub
Author: Agent Hub SDK Maintainers
License: Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click<9,>=8.1
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# smart-agenthub

Python SDK and CLI for managing knowledge bases and Agents, and for invoking a
published Agent from an application.

## Table of Contents

- [Requirements](#requirements)
- [Install](#install)
- [Management Client](#management-client)
- [Knowledge-base Workflow](#knowledge-base-workflow)
- [Application Client](#application-client)
- [Async Usage](#async-usage)
- [CLI](#cli)
- [Errors](#errors)
- [Naming and Return Values](#naming-and-return-values)
- [Module Overview](#module-overview)
- [Complete Method Reference](#complete-method-reference)

## Requirements

- Python 3.10 or newer
- An Agent Hub server URL
- An API Key for management workflows, or an Agent Key for application calls

## Install

```bash
python -m pip install smart-agenthub
```

Pin a version for reproducible deployments:

```bash
python -m pip install smart-agenthub==0.1.1
```

## Management Client

Use `AgentHubClient` to configure models, knowledge bases, documents, Agents,
credentials and sessions.

```python
import os

from smart_agenthub import AgentHubClient

with AgentHubClient(
    os.environ["AGENTHUB_BASE_URL"],
    api_key=os.environ["AGENTHUB_API_KEY"],
    timeout=30.0,
    max_retries=2,
) as client:
    agents = client.agents.list()
    knowledge_bases = client.knowledge_bases.list()
```

The client accepts either `api_key` or `token`, never both. API Keys are intended
for long-lived automation. `token` is available only when the caller already owns
a short-lived bearer token; the SDK does not implement account login or captcha.

## Knowledge-base Workflow

```python
import os
import uuid

from smart_agenthub import AgentHubClient

with AgentHubClient(
    os.environ["AGENTHUB_BASE_URL"],
    api_key=os.environ["AGENTHUB_API_KEY"],
) as client:
    kb = client.knowledge_bases.create(
        body={
            "name": "Product documentation",
            "index_mode": "KEYWORD",
        }
    )
    upload = client.documents.upload(
        kb["id"],
        "guide.pdf",
        idempotency_key=str(uuid.uuid4()),
    )
    document = client.wait_for_document(
        upload["document"]["id"],
        timeout=900,
    )
```

For semantic or hybrid retrieval, select a ready embedding space when creating the
knowledge base. Use `wait_for_rebuild()` after changing index capabilities through a
rebuild request.

## Application Client

`AgentClient` requires one published Agent ID and its Agent Key. It cannot call
management APIs.

### Non-streaming response

```python
import os
import uuid

from smart_agenthub import AgentClient

with AgentClient(
    os.environ["AGENTHUB_BASE_URL"],
    agent_id=os.environ["AGENTHUB_AGENT_ID"],
    api_key=os.environ["AGENTHUB_AGENT_API_KEY"],
) as agent:
    response = agent.chat(
        [{"role": "user", "content": "What changed in the latest guide?"}],
        idempotency_key=str(uuid.uuid4()),
        stream=False,
    )
```

### Streaming response

```python
with AgentClient(
    os.environ["AGENTHUB_BASE_URL"],
    agent_id=os.environ["AGENTHUB_AGENT_ID"],
    api_key=os.environ["AGENTHUB_AGENT_API_KEY"],
) as agent:
    for event in agent.chat(
        [{"role": "user", "content": "Summarize the onboarding guide."}]
    ):
        if event.data == "[DONE]":
            break
        print(event.data)
```

Retain the returned `session_id`, `turn_id` and latest SSE event ID. If a stream
disconnects, inspect the turn with `get_turn()` and continue with
`resume(turn_id, last_event_id=...)`. Do not create a second turn solely because the
original stream disconnected.

`upload()` attaches a local file to an Agent conversation. Pass the returned file
reference in `attachments` on a later `chat()` call.

## Async Usage

`AsyncAgentHubClient` and `AsyncAgentClient` expose matching resources and methods.
Streaming methods return async iterators.

```python
import asyncio
import os

from smart_agenthub import AsyncAgentHubClient


async def main() -> None:
    async with AsyncAgentHubClient(
        os.environ["AGENTHUB_BASE_URL"],
        api_key=os.environ["AGENTHUB_API_KEY"],
    ) as client:
        print(await client.agents.list())


asyncio.run(main())
```

## CLI

The package installs `agenthub`.

```bash
agenthub login --base-url https://agent.example.com
agenthub whoami

agenthub agents list
agenthub knowledge-bases list
agenthub documents upload <kb-id> ./guide.pdf \
  --idempotency-key upload-guide-001

agenthub --json agent chat \
  --agent-id "$AGENTHUB_AGENT_ID" \
  --agent-key "$AGENTHUB_AGENT_API_KEY" \
  --message "Summarize the onboarding guide."

agenthub logout
```

`login` validates and saves an API Key in `~/.agenthub/credentials.json`; it does
not perform account login or create a bearer token. The credential directory and
file use private permissions and writes are atomic. Agent Keys and short-lived
bearer tokens are never saved.

For non-interactive use, configure:

```bash
export AGENTHUB_BASE_URL=https://agent.example.com
export AGENTHUB_API_KEY='<management-api-key>'
```

Global `--json` produces one JSON value for normal commands, `null` for empty
responses, JSON Lines for streams and a structured error object on stderr.

## Errors

All SDK exceptions inherit from `AgentHubError`. HTTP failures are mapped to typed
exceptions such as `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
`ConflictError`, `ValidationError`, `RateLimitError` and `ServerError`.

```python
from smart_agenthub import AgentHubError, RateLimitError

try:
    result = client.agents.list()
except RateLimitError as exc:
    print(exc.retry_after, exc.request_id)
except AgentHubError as exc:
    print(str(exc))
```

API errors expose `status_code`, `code`, `request_id`, `retry_after` and `details`
when supplied by the server. Exception messages do not contain credentials or raw
secret-bearing response bodies.

## Naming and Return Values

- Resource methods use `snake_case`.
- JSON request and response keys keep their wire names.
- Business methods return the response envelope's `data` value.
- HTTP 204 operations return `None`.
- Pagination remains explicit; callers choose page boundaries.

The complete endpoint, parameter, request and response schemas are listed below.

<!-- BEGIN GENERATED METHOD REFERENCE -->
## Module Overview

| Module | Accessor | Operations | Purpose |
| --- | --- | ---: | --- |
| `api_keys` | `client.api_keys` | 3 | Management API Key lifecycle |
| `models` | `client.models` | 9 | Model discovery and registry lifecycle |
| `model_revisions` | `client.model_revisions` | 2 | Immutable model endpoint revisions |
| `model_credentials` | `client.model_credentials` | 2 | Model credential metadata and rotation |
| `embedding_spaces` | `client.embedding_spaces` | 1 | Ready embedding-space discovery |
| `knowledge_bases` | `client.knowledge_bases` | 10 | Knowledge-base lifecycle and retrieval |
| `documents` | `client.documents` | 6 | Document upload and parse lifecycle |
| `agents` | `client.agents` | 8 | Agent definition and publication lifecycle |
| `agent_keys` | `client.agent_keys` | 4 | Application-facing Agent Key lifecycle |
| `sessions` | `client.sessions` | 3 | Conversation inspection and closure |
| `observability` | `client.observability` | 2 | Agent and knowledge-base dashboards |
| `agent` | `agent` | 7 | Published Agent invocation |

## Complete Method Reference

This section documents all **57 wrapped HTTP operations**. It is generated from the same contract as the SDK so Python and TypeScript stay aligned.

`AsyncAgentHubClient` and `AsyncAgentClient` expose the same resource names, method arguments, request bodies and responses; await non-streaming calls and iterate streaming results with `async for`.

Authentication headers are added by the client. JSON methods return the normal response envelope's `data` value; the HTTP response tables show the complete wire schemas. JSON field names remain `snake_case` in both languages.

### Agent Hub API Keys

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.api_keys.list()` | List Api Keys | body: none | array<[AgentHubApiKeyView](#schema-agenthubapikeyview)> |
| `client.api_keys.create(*, body)` | Create Api Key | body: [AgentHubApiKeyCreate](#schema-agenthubapikeycreate) (required) | [AgentHubApiKeyCreated](#schema-agenthubapikeycreated) |
| `client.api_keys.revoke(key_id)` | Revoke Api Key | path: `key_id` (required); body: none | no value |

<a id="method-api_keys-list"></a>
#### `client.api_keys.list()`

List Api Keys

- **HTTP:** `GET /agent-hub/api/v1/api-keys`
- **CLI:** `agenthub api-keys list`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

No request body.

**SDK response**

Returns array<[AgentHubApiKeyView](#schema-agenthubapikeyview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_AgentHubApiKeyView__](#schema-apiresponse-list-agenthubapikeyview) | Successful Response |

<a id="method-api_keys-create"></a>
#### `client.api_keys.create(*, body)`

Create Api Key

- **HTTP:** `POST /agent-hub/api/v1/api-keys`
- **CLI:** `agenthub api-keys create --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [AgentHubApiKeyCreate](#schema-agenthubapikeycreate) |

**SDK response**

Returns [AgentHubApiKeyCreated](#schema-agenthubapikeycreated).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_AgentHubApiKeyCreated_](#schema-apiresponse-agenthubapikeycreated) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-api_keys-revoke"></a>
#### `client.api_keys.revoke(key_id)`

Revoke Api Key

- **HTTP:** `DELETE /agent-hub/api/v1/api-keys/{key_id}`
- **CLI:** `agenthub api-keys revoke <key-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `key_id` | `key_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Models

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.models.catalog()` | List Models | body: none | array<[ModelCatalogItem](#schema-modelcatalogitem)> |
| `client.models.import_msp(*, body)` | Import Msp Model | body: [MspModelImport](#schema-mspmodelimport) (required) | [MspModelImportView](#schema-mspmodelimportview) |
| `client.models.get_msp(service_id)` | Msp Model Detail | path: `service_id` (required); body: none | [ModelCatalogItem](#schema-modelcatalogitem) |
| `client.models.list(*, status_filter=None)` | List Registry | query: `status_filter`; body: none | array<[ModelRefView](#schema-modelrefview)> |
| `client.models.create(*, body)` | Create Registry | body: [ModelRefCreate](#schema-modelrefcreate) (required) | [ModelRefView](#schema-modelrefview) |
| `client.models.delete(model_ref_id, *, expected_revision)` | Delete Registry | path: `model_ref_id` (required); query: `expected_revision` (required); body: none | no value |
| `client.models.get(model_ref_id)` | Get Registry | path: `model_ref_id` (required); body: none | [ModelRefView](#schema-modelrefview) |
| `client.models.update(model_ref_id, *, body)` | Update Registry | path: `model_ref_id` (required); body: [ModelRefUpdate](#schema-modelrefupdate) (required) | [ModelRefView](#schema-modelrefview) |
| `client.models.change_lifecycle(model_ref_id, *, body)` | Registry Lifecycle | path: `model_ref_id` (required); body: [ModelLifecycleAction](#schema-modellifecycleaction) (required) | [ModelRefView](#schema-modelrefview) |

<a id="method-models-catalog"></a>
#### `client.models.catalog()`

List Models

- **HTTP:** `GET /agent-hub/api/v1/models`
- **CLI:** `agenthub models catalog`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

No request body.

**SDK response**

Returns array<[ModelCatalogItem](#schema-modelcatalogitem)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_ModelCatalogItem__](#schema-apiresponse-list-modelcatalogitem) | Successful Response |

<a id="method-models-import_msp"></a>
#### `client.models.import_msp(*, body)`

Import Msp Model

- **HTTP:** `POST /agent-hub/api/v1/models/msp/import`
- **CLI:** `agenthub models import-msp --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [MspModelImport](#schema-mspmodelimport) |

**SDK response**

Returns [MspModelImportView](#schema-mspmodelimportview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_MspModelImportView_](#schema-apiresponse-mspmodelimportview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-get_msp"></a>
#### `client.models.get_msp(service_id)`

Msp Model Detail

- **HTTP:** `GET /agent-hub/api/v1/models/msp/{service_id}`
- **CLI:** `agenthub models get-msp <service-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `service_id` | `service_id` | string | yes | - |

**Request body**

No request body.

**SDK response**

Returns [ModelCatalogItem](#schema-modelcatalogitem).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ModelCatalogItem_](#schema-apiresponse-modelcatalogitem) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-list"></a>
#### `client.models.list(*, status_filter=None)`

List Registry

- **HTTP:** `GET /agent-hub/api/v1/models/registry`
- **CLI:** `agenthub models list --status-filter <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `status_filter` | `status_filter` | string \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns array<[ModelRefView](#schema-modelrefview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_ModelRefView__](#schema-apiresponse-list-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-create"></a>
#### `client.models.create(*, body)`

Create Registry

- **HTTP:** `POST /agent-hub/api/v1/models/registry`
- **CLI:** `agenthub models create --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ModelRefCreate](#schema-modelrefcreate) |

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-delete"></a>
#### `client.models.delete(model_ref_id, *, expected_revision)`

Delete Registry

- **HTTP:** `DELETE /agent-hub/api/v1/models/registry/{model_ref_id}`
- **CLI:** `agenthub models delete <model-ref-id> --expected-revision <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |
| query | `expected_revision` | `expected_revision` | integer | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-get"></a>
#### `client.models.get(model_ref_id)`

Get Registry

- **HTTP:** `GET /agent-hub/api/v1/models/registry/{model_ref_id}`
- **CLI:** `agenthub models get <model-ref-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-update"></a>
#### `client.models.update(model_ref_id, *, body)`

Update Registry

- **HTTP:** `PUT /agent-hub/api/v1/models/registry/{model_ref_id}`
- **CLI:** `agenthub models update <model-ref-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ModelRefUpdate](#schema-modelrefupdate) |

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-models-change_lifecycle"></a>
#### `client.models.change_lifecycle(model_ref_id, *, body)`

Registry Lifecycle

- **HTTP:** `POST /agent-hub/api/v1/models/registry/{model_ref_id}/lifecycle`
- **CLI:** `agenthub models change-lifecycle <model-ref-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ModelLifecycleAction](#schema-modellifecycleaction) |

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Model Revisions

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.model_revisions.list(model_ref_id)` | List Registry Revisions | path: `model_ref_id` (required); body: none | array<[ModelRefRevisionView](#schema-modelrefrevisionview)> |
| `client.model_revisions.create(model_ref_id, *, body)` | Add Registry Revision | path: `model_ref_id` (required); body: [ModelRevisionCreate](#schema-modelrevisioncreate) (required) | [ModelRefView](#schema-modelrefview) |

<a id="method-model_revisions-list"></a>
#### `client.model_revisions.list(model_ref_id)`

List Registry Revisions

- **HTTP:** `GET /agent-hub/api/v1/models/registry/{model_ref_id}/revisions`
- **CLI:** `agenthub model-revisions list <model-ref-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns array<[ModelRefRevisionView](#schema-modelrefrevisionview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_ModelRefRevisionView__](#schema-apiresponse-list-modelrefrevisionview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-model_revisions-create"></a>
#### `client.model_revisions.create(model_ref_id, *, body)`

Add Registry Revision

- **HTTP:** `POST /agent-hub/api/v1/models/registry/{model_ref_id}/revisions`
- **CLI:** `agenthub model-revisions create <model-ref-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ModelRevisionCreate](#schema-modelrevisioncreate) |

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Model Credentials

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.model_credentials.list(model_ref_id)` | List Registry Credentials | path: `model_ref_id` (required); body: none | array<[ModelCredentialView](#schema-modelcredentialview)> |
| `client.model_credentials.rotate(model_ref_id, *, body)` | Rotate Registry Credential | path: `model_ref_id` (required); body: [ModelCredentialRotate](#schema-modelcredentialrotate) (required) | [ModelRefView](#schema-modelrefview) |

<a id="method-model_credentials-list"></a>
#### `client.model_credentials.list(model_ref_id)`

List Registry Credentials

- **HTTP:** `GET /agent-hub/api/v1/models/registry/{model_ref_id}/credentials`
- **CLI:** `agenthub model-credentials list <model-ref-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns array<[ModelCredentialView](#schema-modelcredentialview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_ModelCredentialView__](#schema-apiresponse-list-modelcredentialview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-model_credentials-rotate"></a>
#### `client.model_credentials.rotate(model_ref_id, *, body)`

Rotate Registry Credential

- **HTTP:** `POST /agent-hub/api/v1/models/registry/{model_ref_id}/credentials/rotate`
- **CLI:** `agenthub model-credentials rotate <model-ref-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `model_ref_id` | `model_ref_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ModelCredentialRotate](#schema-modelcredentialrotate) |

**SDK response**

Returns [ModelRefView](#schema-modelrefview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ModelRefView_](#schema-apiresponse-modelrefview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Embedding Spaces

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.embedding_spaces.list(*, status=None)` | List Embedding Spaces | query: `status`; body: none | [PageResult_EmbeddingSpaceView_](#schema-pageresult-embeddingspaceview) |

<a id="method-embedding_spaces-list"></a>
#### `client.embedding_spaces.list(*, status=None)`

List Embedding Spaces

- **HTTP:** `GET /agent-hub/api/v1/embedding-spaces`
- **CLI:** `agenthub embedding-spaces list --status <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `status` | `status` | [EmbeddingSpaceStatus](#schema-embeddingspacestatus) \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns [PageResult_EmbeddingSpaceView_](#schema-pageresult-embeddingspaceview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_EmbeddingSpaceView__](#schema-apiresponse-pageresult-embeddingspaceview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Knowledge Bases

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.knowledge_bases.list(*, status=None, include_index_capabilities=None)` | List Knowledge Bases | query: `status`, `include_index_capabilities`; body: none | [PageResult_KnowledgeBaseSelection_](#schema-pageresult-knowledgebaseselection) |
| `client.knowledge_bases.create(*, body)` | Create Knowledge Base | body: [KnowledgeBaseCreate](#schema-knowledgebasecreate) (required) | [KnowledgeBaseView](#schema-knowledgebaseview) |
| `client.knowledge_bases.parser_preflight(*, body)` | Preflight Knowledge Base Parser | body: [ParserPreflightRequest](#schema-parserpreflightrequest) (required) | [ParserPreflightView](#schema-parserpreflightview) |
| `client.knowledge_bases.delete(kb_id)` | Delete Knowledge Base | path: `kb_id` (required); body: none | no value |
| `client.knowledge_bases.get(kb_id)` | Get Knowledge Base | path: `kb_id` (required); body: none | [KnowledgeBaseView](#schema-knowledgebaseview) |
| `client.knowledge_bases.update(kb_id, *, body)` | Update Knowledge Base | path: `kb_id` (required); body: [KnowledgeBaseUpdate](#schema-knowledgebaseupdate) (required) | [KnowledgeBaseView](#schema-knowledgebaseview) |
| `client.knowledge_bases.list_chunks(kb_id)` | List Chunks | path: `kb_id` (required); body: none | [PageResult_ChunkPreview_](#schema-pageresult-chunkpreview) |
| `client.knowledge_bases.latest_rebuild(kb_id)` | Get Latest Rebuild Job | path: `kb_id` (required); body: none | [RebuildJobView](#schema-rebuildjobview) |
| `client.knowledge_bases.rebuild(kb_id, *, body=None, idempotency_key)` | Rebuild Knowledge Base | path: `kb_id` (required); header: `Idempotency-Key` (required); body: [RebuildRequest](#schema-rebuildrequest) \| null (optional) | [RebuildJobView](#schema-rebuildjobview) |
| `client.knowledge_bases.test_retrieval(kb_id, *, body)` | Retrieval Test | path: `kb_id` (required); body: [RetrievalTestRequest](#schema-retrievaltestrequest) (required) | [PageResult_RetrievalPreview_](#schema-pageresult-retrievalpreview) |

<a id="method-knowledge_bases-list"></a>
#### `client.knowledge_bases.list(*, status=None, include_index_capabilities=None)`

List Knowledge Bases

- **HTTP:** `GET /agent-hub/api/v1/kbs`
- **CLI:** `agenthub knowledge-bases list --status <value> --include-index-capabilities <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `status` | `status` | [KnowledgeBaseStatus](#schema-knowledgebasestatus) \| null | no | - |
| query | `include_index_capabilities` | `include_index_capabilities` | boolean | no | default: `false` |

**Request body**

No request body.

**SDK response**

Returns [PageResult_KnowledgeBaseSelection_](#schema-pageresult-knowledgebaseselection).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_KnowledgeBaseSelection__](#schema-apiresponse-pageresult-knowledgebaseselection) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-create"></a>
#### `client.knowledge_bases.create(*, body)`

Create Knowledge Base

- **HTTP:** `POST /agent-hub/api/v1/kbs`
- **CLI:** `agenthub knowledge-bases create --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [KnowledgeBaseCreate](#schema-knowledgebasecreate) |

**SDK response**

Returns [KnowledgeBaseView](#schema-knowledgebaseview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_KnowledgeBaseView_](#schema-apiresponse-knowledgebaseview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-parser_preflight"></a>
#### `client.knowledge_bases.parser_preflight(*, body)`

Preflight Knowledge Base Parser

- **HTTP:** `POST /agent-hub/api/v1/kbs/parser-preflight`
- **CLI:** `agenthub knowledge-bases parser-preflight --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ParserPreflightRequest](#schema-parserpreflightrequest) |

**SDK response**

Returns [ParserPreflightView](#schema-parserpreflightview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_ParserPreflightView_](#schema-apiresponse-parserpreflightview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-delete"></a>
#### `client.knowledge_bases.delete(kb_id)`

Delete Knowledge Base

- **HTTP:** `DELETE /agent-hub/api/v1/kbs/{kb_id}`
- **CLI:** `agenthub knowledge-bases delete <kb-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-get"></a>
#### `client.knowledge_bases.get(kb_id)`

Get Knowledge Base

- **HTTP:** `GET /agent-hub/api/v1/kbs/{kb_id}`
- **CLI:** `agenthub knowledge-bases get <kb-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [KnowledgeBaseView](#schema-knowledgebaseview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_KnowledgeBaseView_](#schema-apiresponse-knowledgebaseview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-update"></a>
#### `client.knowledge_bases.update(kb_id, *, body)`

Update Knowledge Base

- **HTTP:** `PUT /agent-hub/api/v1/kbs/{kb_id}`
- **CLI:** `agenthub knowledge-bases update <kb-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [KnowledgeBaseUpdate](#schema-knowledgebaseupdate) |

**SDK response**

Returns [KnowledgeBaseView](#schema-knowledgebaseview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_KnowledgeBaseView_](#schema-apiresponse-knowledgebaseview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-list_chunks"></a>
#### `client.knowledge_bases.list_chunks(kb_id)`

List Chunks

- **HTTP:** `GET /agent-hub/api/v1/kbs/{kb_id}/chunks`
- **CLI:** `agenthub knowledge-bases list-chunks <kb-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [PageResult_ChunkPreview_](#schema-pageresult-chunkpreview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_ChunkPreview__](#schema-apiresponse-pageresult-chunkpreview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-latest_rebuild"></a>
#### `client.knowledge_bases.latest_rebuild(kb_id)`

Get Latest Rebuild Job

- **HTTP:** `GET /agent-hub/api/v1/kbs/{kb_id}/rebuild`
- **CLI:** `agenthub knowledge-bases latest-rebuild <kb-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [RebuildJobView](#schema-rebuildjobview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_RebuildJobView_](#schema-apiresponse-rebuildjobview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-rebuild"></a>
#### `client.knowledge_bases.rebuild(kb_id, *, body=None, idempotency_key)`

Rebuild Knowledge Base

- **HTTP:** `POST /agent-hub/api/v1/kbs/{kb_id}/rebuild`
- **CLI:** `agenthub knowledge-bases rebuild <kb-id> --body <json|@file|-> --idempotency-key <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |
| header | `idempotency_key` | `Idempotency-Key` | string | yes | min length: `1`; max length: `128` |

**Request body**

Required: **no**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [RebuildRequest](#schema-rebuildrequest) \| null |

**SDK response**

Returns [RebuildJobView](#schema-rebuildjobview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `202` | `application/json` | [ApiResponse_RebuildJobView_](#schema-apiresponse-rebuildjobview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-knowledge_bases-test_retrieval"></a>
#### `client.knowledge_bases.test_retrieval(kb_id, *, body)`

Retrieval Test

- **HTTP:** `POST /agent-hub/api/v1/kbs/{kb_id}/retrieval-test`
- **CLI:** `agenthub knowledge-bases test-retrieval <kb-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [RetrievalTestRequest](#schema-retrievaltestrequest) |

**SDK response**

Returns [PageResult_RetrievalPreview_](#schema-pageresult-retrievalpreview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_RetrievalPreview__](#schema-apiresponse-pageresult-retrievalpreview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Documents

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.documents.delete(document_id)` | Delete Document | path: `document_id` (required); body: none | no value |
| `client.documents.reparse(document_id, *, idempotency_key)` | Reparse Document | path: `document_id` (required); header: `Idempotency-Key` (required); body: none | [DocumentUploadResult](#schema-documentuploadresult) |
| `client.documents.list_revisions(document_id)` | List Document Revisions | path: `document_id` (required); body: none | [PageResult_DocumentRevisionView_](#schema-pageresult-documentrevisionview) |
| `client.documents.get_revision(document_id, revision_id)` | Get Document Revision | path: `document_id` (required), `revision_id` (required); body: none | [DocumentRevisionView](#schema-documentrevisionview) |
| `client.documents.list(kb_id, *, page=None, page_size=None, status=None)` | List Documents | path: `kb_id` (required); query: `page`, `pageSize`, `status`; body: none | [PageResult_DocumentView_](#schema-pageresult-documentview) |
| `client.documents.upload(kb_id, path, *, idempotency_key)` | Upload Document | path: `kb_id` (required); header: `Idempotency-Key` (required); body: [Body_upload_document_agent_hub_api_v1_kbs__kb_id__documents_post](#schema-body-upload-document-agent-hub-api-v1-kbs-kb-id-documents-post) (required) | [DocumentUploadResult](#schema-documentuploadresult) |

<a id="method-documents-delete"></a>
#### `client.documents.delete(document_id)`

Delete Document

- **HTTP:** `DELETE /agent-hub/api/v1/documents/{document_id}`
- **CLI:** `agenthub documents delete <document-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `document_id` | `document_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-documents-reparse"></a>
#### `client.documents.reparse(document_id, *, idempotency_key)`

Reparse Document

- **HTTP:** `POST /agent-hub/api/v1/documents/{document_id}/reparse`
- **CLI:** `agenthub documents reparse <document-id> --idempotency-key <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `document_id` | `document_id` | string (uuid) | yes | - |
| header | `idempotency_key` | `Idempotency-Key` | string | yes | min length: `1`; max length: `128` |

**Request body**

No request body.

**SDK response**

Returns [DocumentUploadResult](#schema-documentuploadresult).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `202` | `application/json` | [ApiResponse_DocumentUploadResult_](#schema-apiresponse-documentuploadresult) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-documents-list_revisions"></a>
#### `client.documents.list_revisions(document_id)`

List Document Revisions

- **HTTP:** `GET /agent-hub/api/v1/documents/{document_id}/revisions`
- **CLI:** `agenthub documents list-revisions <document-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `document_id` | `document_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [PageResult_DocumentRevisionView_](#schema-pageresult-documentrevisionview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_DocumentRevisionView__](#schema-apiresponse-pageresult-documentrevisionview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-documents-get_revision"></a>
#### `client.documents.get_revision(document_id, revision_id)`

Get Document Revision

- **HTTP:** `GET /agent-hub/api/v1/documents/{document_id}/revisions/{revision_id}`
- **CLI:** `agenthub documents get-revision <document-id> <revision-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `document_id` | `document_id` | string (uuid) | yes | - |
| path | `revision_id` | `revision_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [DocumentRevisionView](#schema-documentrevisionview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_DocumentRevisionView_](#schema-apiresponse-documentrevisionview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-documents-list"></a>
#### `client.documents.list(kb_id, *, page=None, page_size=None, status=None)`

List Documents

- **HTTP:** `GET /agent-hub/api/v1/kbs/{kb_id}/documents`
- **CLI:** `agenthub documents list <kb-id> --page <value> --page-size <value> --status <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |
| query | `page` | `page` | integer | no | min: `1`; default: `1` |
| query | `page_size` | `pageSize` | integer | no | min: `1`; max: `100`; default: `100` |
| query | `status` | `status` | [DocumentStatus](#schema-documentstatus) \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns [PageResult_DocumentView_](#schema-pageresult-documentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_DocumentView__](#schema-apiresponse-pageresult-documentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-documents-upload"></a>
#### `client.documents.upload(kb_id, path, *, idempotency_key)`

Upload Document

- **HTTP:** `POST /agent-hub/api/v1/kbs/{kb_id}/documents`
- **CLI:** `agenthub documents upload <kb-id> <file> --idempotency-key <key>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `kb_id` | `kb_id` | string (uuid) | yes | - |
| header | `idempotency_key` | `Idempotency-Key` | string | yes | min length: `1`; max length: `128` |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `multipart/form-data` | [Body_upload_document_agent_hub_api_v1_kbs__kb_id__documents_post](#schema-body-upload-document-agent-hub-api-v1-kbs-kb-id-documents-post) |

**SDK response**

Returns [DocumentUploadResult](#schema-documentuploadresult).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `202` | `application/json` | [ApiResponse_DocumentUploadResult_](#schema-apiresponse-documentuploadresult) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Agents

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.agents.list(*, status_filter=None)` | List Agents | query: `status_filter`; body: none | [PageResult_AgentView_](#schema-pageresult-agentview) |
| `client.agents.create(*, body)` | Create Agent | body: [AgentCreate](#schema-agentcreate) (required) | [AgentView](#schema-agentview) |
| `client.agents.preflight(*, body)` | Validate create-and-publish readiness without writing an Agent row. | body: [AgentCreate](#schema-agentcreate) (required) | object<string, boolean> |
| `client.agents.delete(agent_id)` | Delete Agent | path: `agent_id` (required); body: none | no value |
| `client.agents.get(agent_id)` | Get Agent | path: `agent_id` (required); body: none | [AgentView](#schema-agentview) |
| `client.agents.update(agent_id, *, body)` | Update Agent | path: `agent_id` (required); body: [AgentUpdate](#schema-agentupdate) (required) | [AgentView](#schema-agentview) |
| `client.agents.offline(agent_id)` | Offline Agent | path: `agent_id` (required); body: none | [AgentView](#schema-agentview) |
| `client.agents.publish(agent_id)` | Publish Agent | path: `agent_id` (required); body: none | [AgentView](#schema-agentview) |

<a id="method-agents-list"></a>
#### `client.agents.list(*, status_filter=None)`

List Agents

- **HTTP:** `GET /agent-hub/api/v1/agents`
- **CLI:** `agenthub agents list --status-filter <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `status_filter` | `status_filter` | [AgentStatus](#schema-agentstatus) \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns [PageResult_AgentView_](#schema-pageresult-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_AgentView__](#schema-apiresponse-pageresult-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-create"></a>
#### `client.agents.create(*, body)`

Create Agent

- **HTTP:** `POST /agent-hub/api/v1/agents`
- **CLI:** `agenthub agents create --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [AgentCreate](#schema-agentcreate) |

**SDK response**

Returns [AgentView](#schema-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_AgentView_](#schema-apiresponse-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-preflight"></a>
#### `client.agents.preflight(*, body)`

Validate create-and-publish readiness without writing an Agent row.

- **HTTP:** `POST /agent-hub/api/v1/agents/preflight`
- **CLI:** `agenthub agents preflight --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [AgentCreate](#schema-agentcreate) |

**SDK response**

Returns object<string, boolean>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_dict_str__bool__](#schema-apiresponse-dict-str-bool) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-delete"></a>
#### `client.agents.delete(agent_id)`

Delete Agent

- **HTTP:** `DELETE /agent-hub/api/v1/agents/{agent_id}`
- **CLI:** `agenthub agents delete <agent-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-get"></a>
#### `client.agents.get(agent_id)`

Get Agent

- **HTTP:** `GET /agent-hub/api/v1/agents/{agent_id}`
- **CLI:** `agenthub agents get <agent-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [AgentView](#schema-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentView_](#schema-apiresponse-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-update"></a>
#### `client.agents.update(agent_id, *, body)`

Update Agent

- **HTTP:** `PUT /agent-hub/api/v1/agents/{agent_id}`
- **CLI:** `agenthub agents update <agent-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [AgentUpdate](#schema-agentupdate) |

**SDK response**

Returns [AgentView](#schema-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentView_](#schema-apiresponse-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-offline"></a>
#### `client.agents.offline(agent_id)`

Offline Agent

- **HTTP:** `POST /agent-hub/api/v1/agents/{agent_id}/offline`
- **CLI:** `agenthub agents offline <agent-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [AgentView](#schema-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentView_](#schema-apiresponse-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agents-publish"></a>
#### `client.agents.publish(agent_id)`

Publish Agent

- **HTTP:** `POST /agent-hub/api/v1/agents/{agent_id}/publish`
- **CLI:** `agenthub agents publish <agent-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [AgentView](#schema-agentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentView_](#schema-apiresponse-agentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Agent API Keys

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.agent_keys.list(agent_id)` | List Agent Keys | path: `agent_id` (required); body: none | array<[AgentKeyView](#schema-agentkeyview)> |
| `client.agent_keys.create(agent_id, *, body)` | Create Agent Key | path: `agent_id` (required); body: [AgentKeyCreate](#schema-agentkeycreate) (required) | [AgentKeyCreated](#schema-agentkeycreated) |
| `client.agent_keys.revoke(agent_id, key_id)` | Revoke Agent Key | path: `agent_id` (required), `key_id` (required); body: none | no value |
| `client.agent_keys.reveal(agent_id, key_id)` | Reveal Agent Key Secret | path: `agent_id` (required), `key_id` (required); body: none | [AgentKeySecret](#schema-agentkeysecret) |

<a id="method-agent_keys-list"></a>
#### `client.agent_keys.list(agent_id)`

List Agent Keys

- **HTTP:** `GET /agent-hub/api/v1/agents/{agent_id}/keys`
- **CLI:** `agenthub agent-keys list <agent-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns array<[AgentKeyView](#schema-agentkeyview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_AgentKeyView__](#schema-apiresponse-list-agentkeyview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent_keys-create"></a>
#### `client.agent_keys.create(agent_id, *, body)`

Create Agent Key

- **HTTP:** `POST /agent-hub/api/v1/agents/{agent_id}/keys`
- **CLI:** `agenthub agent-keys create <agent-id> --body <json|@file|->`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [AgentKeyCreate](#schema-agentkeycreate) |

**SDK response**

Returns [AgentKeyCreated](#schema-agentkeycreated).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [ApiResponse_AgentKeyCreated_](#schema-apiresponse-agentkeycreated) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent_keys-revoke"></a>
#### `client.agent_keys.revoke(agent_id, key_id)`

Revoke Agent Key

- **HTTP:** `DELETE /agent-hub/api/v1/agents/{agent_id}/keys/{key_id}`
- **CLI:** `agenthub agent-keys revoke <agent-id> <key-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |
| path | `key_id` | `key_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent_keys-reveal"></a>
#### `client.agent_keys.reveal(agent_id, key_id)`

Reveal Agent Key Secret

- **HTTP:** `GET /agent-hub/api/v1/agents/{agent_id}/keys/{key_id}/secret`
- **CLI:** `agenthub agent-keys reveal <agent-id> <key-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `agent_id` | `agent_id` | string (uuid) | yes | - |
| path | `key_id` | `key_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [AgentKeySecret](#schema-agentkeysecret).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentKeySecret_](#schema-apiresponse-agentkeysecret) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Sessions

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.sessions.list(*, agent_id=None, status=None, channel=None, search=None, mine=None, page=None, page_size=None)` | List Sessions | query: `agent_id`, `status`, `channel`, `search`, `mine`, `page`, `pageSize`; body: none | [PageResult_SessionView_](#schema-pageresult-sessionview) |
| `client.sessions.close(session_id)` | Close Session | path: `session_id` (required); body: none | no value |
| `client.sessions.messages(session_id)` | Session Messages | path: `session_id` (required); body: none | array<[MessageView](#schema-messageview)> |

<a id="method-sessions-list"></a>
#### `client.sessions.list(*, agent_id=None, status=None, channel=None, search=None, mine=None, page=None, page_size=None)`

List Sessions

- **HTTP:** `GET /agent-hub/api/v1/sessions`
- **CLI:** `agenthub sessions list --agent-id <value> --status <value> --channel <value> --search <value> --mine <value> --page <value> --page-size <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `agent_id` | `agent_id` | string (uuid) \| null | no | - |
| query | `status` | `status` | [SessionStatus](#schema-sessionstatus) \| null | no | - |
| query | `channel` | `channel` | string \| null | no | - |
| query | `search` | `search` | string \| null | no | - |
| query | `mine` | `mine` | boolean | no | default: `false` |
| query | `page` | `page` | integer | no | min: `1`; default: `1` |
| query | `page_size` | `pageSize` | integer | no | min: `1`; max: `100`; default: `20` |

**Request body**

No request body.

**SDK response**

Returns [PageResult_SessionView_](#schema-pageresult-sessionview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_PageResult_SessionView__](#schema-apiresponse-pageresult-sessionview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-sessions-close"></a>
#### `client.sessions.close(session_id)`

Close Session

- **HTTP:** `DELETE /agent-hub/api/v1/sessions/{session_id}`
- **CLI:** `agenthub sessions close <session-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `session_id` | `session_id` | string | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-sessions-messages"></a>
#### `client.sessions.messages(session_id)`

Session Messages

- **HTTP:** `GET /agent-hub/api/v1/sessions/{session_id}/messages`
- **CLI:** `agenthub sessions messages <session-id>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `session_id` | `session_id` | string | yes | - |

**Request body**

No request body.

**SDK response**

Returns array<[MessageView](#schema-messageview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_MessageView__](#schema-apiresponse-list-messageview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Observability

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `client.observability.agents(*, window=None, agent_id=None)` | Agents | query: `window`, `agent_id`; body: none | [AgentDashboard](#schema-agentdashboard) |
| `client.observability.knowledge_bases(*, window=None, kb_id=None, page=None, page_size=None)` | Knowledge Bases | query: `window`, `kb_id`, `page`, `page_size`; body: none | [KnowledgeDashboard](#schema-knowledgedashboard) |

<a id="method-observability-agents"></a>
#### `client.observability.agents(*, window=None, agent_id=None)`

Agents

- **HTTP:** `GET /agent-hub/api/v1/observability/agents`
- **CLI:** `agenthub observability agents --window <value> --agent-id <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `window` | `window` | `"1h"` \| `"24h"` \| `"7d"` | no | default: `"24h"` |
| query | `agent_id` | `agent_id` | string (uuid) \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns [AgentDashboard](#schema-agentdashboard).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_AgentDashboard_](#schema-apiresponse-agentdashboard) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-observability-knowledge_bases"></a>
#### `client.observability.knowledge_bases(*, window=None, kb_id=None, page=None, page_size=None)`

Knowledge Bases

- **HTTP:** `GET /agent-hub/api/v1/observability/knowledge-bases`
- **CLI:** `agenthub observability knowledge-bases --window <value> --kb-id <value> --page <value> --page-size <value>`
- **Authentication:** `management_bearer` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| query | `window` | `window` | `"1h"` \| `"24h"` \| `"7d"` | no | default: `"24h"` |
| query | `kb_id` | `kb_id` | string (uuid) \| null | no | - |
| query | `page` | `page` | integer | no | min: `1`; max: `100000`; default: `1` |
| query | `page_size` | `page_size` | integer | no | min: `1`; max: `100`; default: `20` |

**Request body**

No request body.

**SDK response**

Returns [KnowledgeDashboard](#schema-knowledgedashboard).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_KnowledgeDashboard_](#schema-apiresponse-knowledgedashboard) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Application Agent API

| SDK method | Purpose | Request | SDK response |
| --- | --- | --- | --- |
| `agent.chat(messages, *, session_id=None, attachments=None, idempotency_key=None, stream=True, **options)` | Chat Completions | header: `Idempotency-Key` (required); body: [ChatCompletionRequest](#schema-chatcompletionrequest) (required) | JSON object when non-streaming; iterator of `SSEEvent` values when streaming |
| `agent.upload(path)` | Upload Attachment | body: [Body_upload_attachment_agent_hub_openapi_v1_agents__agent_id__files_post](#schema-body-upload-attachment-agent-hub-openapi-v1-agents-agent-id-files-post) (required) | [AttachmentView](#schema-attachmentview) |
| `agent.close_session(session_id)` | Close Session | path: `session_id` (required); body: none | no value |
| `agent.messages(session_id)` | Get Session Messages | path: `session_id` (required); body: none | array<[MessageView](#schema-messageview)> |
| `agent.get_turn(turn_id)` | Get Turn | path: `turn_id` (required); body: none | [TurnView](#schema-turnview) |
| `agent.cancel(turn_id)` | Cancel Turn | path: `turn_id` (required); body: none | object<string, boolean> |
| `agent.resume(turn_id, *, last_event_id=None)` | Get Turn Events | path: `turn_id` (required); header: `Last-Event-ID`; body: none | iterator of `SSEEvent` values |

<a id="method-agent-chat"></a>
#### `agent.chat(messages, *, session_id=None, attachments=None, idempotency_key=None, stream=True, **options)`

Chat Completions

- **HTTP:** `POST /agent-hub/openapi/v1/agents/{agent_id}/chat/completions`
- **CLI:** `agenthub agent chat --agent-id <id> --agent-key <key> --message <text> [--session-id <id>] [--idempotency-key <key>] [--no-stream]`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Behavior:** Idempotency-Key is required. stream=true returns SSE; stream=false returns JSON.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| header | `idempotency_key` | `Idempotency-Key` | string | yes | min length: `8`; max length: `128` |

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `application/json` | [ChatCompletionRequest](#schema-chatcompletionrequest) |

**SDK response**

Returns JSON object when non-streaming; iterator of `SSEEvent` values when streaming.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | none | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-upload_attachment"></a>
#### `agent.upload(path)`

Upload Attachment

- **HTTP:** `POST /agent-hub/openapi/v1/agents/{agent_id}/files`
- **CLI:** `agenthub agent upload <file> --agent-id <id> --agent-key <key>`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Request parameters**

No per-call path, query, or header parameters. Authentication is configured on the client.

**Request body**

Required: **yes**

| Content-Type | Schema |
| --- | --- |
| `multipart/form-data` | [Body_upload_attachment_agent_hub_openapi_v1_agents__agent_id__files_post](#schema-body-upload-attachment-agent-hub-openapi-v1-agents-agent-id-files-post) |

**SDK response**

Returns [AttachmentView](#schema-attachmentview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `201` | `application/json` | [AttachmentView](#schema-attachmentview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-close_session"></a>
#### `agent.close_session(session_id)`

Close Session

- **HTTP:** `POST /agent-hub/openapi/v1/agents/{agent_id}/sessions/{session_id}/close`
- **CLI:** `agenthub agent close-session <session-id> --agent-id <id> --agent-key <key>`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `session_id` | `session_id` | string | yes | - |

**Request body**

No request body.

**SDK response**

Returns no value.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `204` | - | no body | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-messages"></a>
#### `agent.messages(session_id)`

Get Session Messages

- **HTTP:** `GET /agent-hub/openapi/v1/agents/{agent_id}/sessions/{session_id}/messages`
- **CLI:** `agenthub agent messages <session-id> --agent-id <id> --agent-key <key>`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `session_id` | `session_id` | string | yes | - |

**Request body**

No request body.

**SDK response**

Returns array<[MessageView](#schema-messageview)>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_list_MessageView__](#schema-apiresponse-list-messageview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-get_turn"></a>
#### `agent.get_turn(turn_id)`

Get Turn

- **HTTP:** `GET /agent-hub/openapi/v1/agents/{agent_id}/turns/{turn_id}`
- **CLI:** `agenthub agent get-turn <turn-id> --agent-id <id> --agent-key <key>`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `turn_id` | `turn_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns [TurnView](#schema-turnview).

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_TurnView_](#schema-apiresponse-turnview) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-cancel"></a>
#### `agent.cancel(turn_id)`

Cancel Turn

- **HTTP:** `POST /agent-hub/openapi/v1/agents/{agent_id}/turns/{turn_id}/cancel`
- **CLI:** `agenthub agent cancel <turn-id> --agent-id <id> --agent-key <key>`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `turn_id` | `turn_id` | string (uuid) | yes | - |

**Request body**

No request body.

**SDK response**

Returns object<string, boolean>.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | [ApiResponse_dict_str__bool__](#schema-apiresponse-dict-str-bool) | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

<a id="method-agent-resume"></a>
#### `agent.resume(turn_id, *, last_event_id=None)`

Get Turn Events

- **HTTP:** `GET /agent-hub/openapi/v1/agents/{agent_id}/turns/{turn_id}/events`
- **CLI:** `agenthub agent resume <turn-id> --agent-id <id> --agent-key <key> [--last-event-id <id>]`
- **Authentication:** `agent_api_key` configured on the client or CLI.

**Behavior:** Returns recoverable SSE events after Last-Event-ID.

**Request parameters**

| Location | SDK name | Wire name | Type | Required | Constraints/default |
| --- | --- | --- | --- | --- | --- |
| path | `turn_id` | `turn_id` | string (uuid) | yes | - |
| header | `last_event_id` | `Last-Event-ID` | integer \| null | no | - |

**Request body**

No request body.

**SDK response**

Returns iterator of `SSEEvent` values.

**HTTP response bodies**

| HTTP | Content-Type | Schema | Description |
| --- | --- | --- | --- |
| `200` | `application/json` | none | Successful Response |
| `422` | `application/json` | [HTTPValidationError](#schema-httpvalidationerror) | Validation Error |

### Payload Schema Reference

These are the request and response payloads referenced above. Required fields and wire constraints come from the server contract.

<a id="schema-activerebuildsummary"></a>
#### `ActiveRebuildSummary`

Compact progress view embedded in the KB detail response.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `status` | [RebuildJobStatus](#schema-rebuildjobstatus) | yes | - | - |
| `from_generation` | integer | yes | - | - |
| `to_generation` | integer | yes | - | - |
| `document_total` | integer | yes | - | - |
| `documents_ready` | integer | yes | - | - |
| `documents_failed` | integer | yes | - | - |
| `error` | string \| null | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-agentcreate"></a>
#### `AgentCreate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `slug` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `4000`; default: `""` | - |
| `avatar` | string \| null | no | - | - |
| `category` | string \| null | no | - | - |
| `model_ref` | [RegistryModelRef](#schema-registrymodelref) | yes | - | - |
| `temperature` | number | no | min: `0.0`; max: `2.0`; default: `0.7` | - |
| `top_p` | number | no | max: `1.0`; exclusive min: `0.0`; default: `1.0` | - |
| `max_tokens` | integer | no | min: `1.0`; max: `131072.0`; default: `2048` | - |
| `concurrent_agents` | integer | no | min: `1.0`; max: `128.0`; default: `2` | - |
| `system_prompt` | string | no | min length: `1`; max length: `64000`; default: `"You are a helpful assistant. Answer clearly and accurately using the available conversation context and knowledge. If the answer is uncertain, say so."` | - |
| `welcome_message` | string | no | max length: `4000`; default: `""` | - |
| `suggested_questions` | array<string> | no | max items: `20` | - |
| `allow_uploads` | boolean | no | default: `true` | - |
| `retrieval_top_k` | integer | no | min: `1.0`; max: `100.0`; default: `8` | - |
| `score_threshold` | number | no | min: `0.0`; max: `1.0`; default: `0.35` | - |
| `embedding_space_thresholds` | object<string, number> | no | - | - |
| `show_citations` | boolean | no | default: `true` | - |
| `restrict_to_kb` | boolean | no | default: `false` | - |
| `query_rewrite_enabled` | boolean | no | default: `true` | - |
| `retrieval_mode` | `"DENSE"` \| `"KEYWORD"` \| `"HYBRID"` | no | default: `"DENSE"` | - |
| `keyword_algorithm` | `"BM25"` | no | default: `"BM25"` | - |
| `keyword_tokenizer` | `"NGRAM"` \| `"JIEBA_NGRAM"` | no | default: `"NGRAM"` | - |
| `keyword_fuzzy_enabled` | boolean | no | default: `false` | - |
| `hybrid_semantic_weight` | number | no | min: `0.0`; max: `1.0`; default: `0.5` | - |
| `allow_partial_retrieval` | boolean | no | default: `false` | - |
| `rerank_enabled` | boolean | no | default: `false` | - |
| `rerank_model_ref_id` | string (uuid) \| null | no | - | - |
| `kb_ids` | array<string (uuid)> | no | max items: `64` | - |

<a id="schema-agentdashboard"></a>
#### `AgentDashboard`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `window` | `"1h"` \| `"24h"` \| `"7d"` | yes | - | - |
| `start_at` | string (date-time) | yes | - | - |
| `end_at` | string (date-time) | yes | - | - |
| `bucket_seconds` | integer | yes | - | - |
| `summary` | [AgentSummary](#schema-agentsummary) | yes | - | - |
| `trend` | array<[AgentTrend](#schema-agenttrend)> | yes | - | - |
| `recent_failures` | array<[TurnFailure](#schema-turnfailure)> | yes | - | - |

<a id="schema-agenthubapikeycreate"></a>
#### `AgentHubApiKeyCreate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `512`; default: `""` | - |
| `expires_at` | string (date-time) \| null | no | - | - |

<a id="schema-agenthubapikeycreated"></a>
#### `AgentHubApiKeyCreated`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `description` | string | yes | - | - |
| `key_prefix` | string | yes | - | - |
| `key_masked` | string | yes | - | - |
| `secret` | string | yes | - | - |
| `expires_at` | string (date-time) \| null | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-agenthubapikeyview"></a>
#### `AgentHubApiKeyView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `description` | string | yes | - | - |
| `key_prefix` | string | yes | - | - |
| `key_masked` | string | yes | - | - |
| `expires_at` | string (date-time) \| null | yes | - | - |
| `last_used_at` | string (date-time) \| null | yes | - | - |
| `is_active` | boolean | yes | - | - |
| `created_by` | string | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-agentkeycreate"></a>
#### `AgentKeyCreate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `512`; default: `""` | - |
| `scopes` | array<`"chat"`> | no | min items: `1`; max items: `1` | - |
| `expires_at` | string (date-time) \| null | no | - | - |

<a id="schema-agentkeycreated"></a>
#### `AgentKeyCreated`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `description` | string | yes | - | - |
| `key_prefix` | string | yes | - | - |
| `key_masked` | string | yes | - | - |
| `secret` | string | yes | - | - |
| `scopes` | array<string> | yes | - | - |
| `expires_at` | string (date-time) \| null | yes | - | - |

<a id="schema-agentkeysecret"></a>
#### `AgentKeySecret`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `secret` | string | yes | - | - |

<a id="schema-agentkeyview"></a>
#### `AgentKeyView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `description` | string | yes | - | - |
| `key_prefix` | string | yes | - | - |
| `key_masked` | string | yes | - | - |
| `scopes` | array<string> | yes | - | - |
| `expires_at` | string (date-time) \| null | yes | - | - |
| `last_used_at` | string (date-time) \| null | yes | - | - |
| `is_active` | boolean | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-agentstatus"></a>
#### `AgentStatus`

Type: `"DRAFT"` | `"PUBLISHED"` | `"OFFLINE"` | `"DELETED"`

<a id="schema-agentsummary"></a>
#### `AgentSummary`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `requests` | integer | no | default: `0` | - |
| `succeeded` | integer | no | default: `0` | - |
| `failed` | integer | no | default: `0` | - |
| `interrupted` | integer | no | default: `0` | - |
| `running` | integer | no | default: `0` | - |
| `success_rate` | number \| null | no | - | - |
| `rpm` | number | no | default: `0` | - |
| `latency` | [Distribution](#schema-distribution) | no | - | - |
| `model_calls` | integer | no | default: `0` | - |
| `model_failures` | integer | no | default: `0` | - |
| `input_tokens` | integer \| null | no | - | - |
| `output_tokens` | integer \| null | no | - | - |
| `total_tokens` | integer \| null | no | - | - |
| `tpm` | number \| null | no | - | - |
| `usage_reported_calls` | integer | no | default: `0` | - |
| `usage_eligible_calls` | integer | no | default: `0` | - |
| `ttft` | [Distribution](#schema-distribution) | no | - | - |

<a id="schema-agenttrend"></a>
#### `AgentTrend`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `at` | string (date-time) | yes | - | - |
| `requests` | integer | no | default: `0` | - |
| `failed` | integer | no | default: `0` | - |
| `model_calls` | integer | no | default: `0` | - |
| `input_tokens` | integer \| null | no | - | - |
| `output_tokens` | integer \| null | no | - | - |
| `total_tokens` | integer \| null | no | - | - |
| `usage_reported_calls` | integer | no | default: `0` | - |

<a id="schema-agentupdate"></a>
#### `AgentUpdate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `slug` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `4000`; default: `""` | - |
| `avatar` | string \| null | no | - | - |
| `category` | string \| null | no | - | - |
| `model_ref` | [RegistryModelRef](#schema-registrymodelref) | yes | - | - |
| `temperature` | number | no | min: `0.0`; max: `2.0`; default: `0.7` | - |
| `top_p` | number | no | max: `1.0`; exclusive min: `0.0`; default: `1.0` | - |
| `max_tokens` | integer | no | min: `1.0`; max: `131072.0`; default: `2048` | - |
| `concurrent_agents` | integer | no | min: `1.0`; max: `128.0`; default: `2` | - |
| `system_prompt` | string | no | min length: `1`; max length: `64000`; default: `"You are a helpful assistant. Answer clearly and accurately using the available conversation context and knowledge. If the answer is uncertain, say so."` | - |
| `welcome_message` | string | no | max length: `4000`; default: `""` | - |
| `suggested_questions` | array<string> | no | max items: `20` | - |
| `allow_uploads` | boolean | no | default: `true` | - |
| `retrieval_top_k` | integer | no | min: `1.0`; max: `100.0`; default: `8` | - |
| `score_threshold` | number | no | min: `0.0`; max: `1.0`; default: `0.35` | - |
| `embedding_space_thresholds` | object<string, number> | no | - | - |
| `show_citations` | boolean | no | default: `true` | - |
| `restrict_to_kb` | boolean | no | default: `false` | - |
| `query_rewrite_enabled` | boolean | no | default: `true` | - |
| `retrieval_mode` | `"DENSE"` \| `"KEYWORD"` \| `"HYBRID"` | no | default: `"DENSE"` | - |
| `keyword_algorithm` | `"BM25"` | no | default: `"BM25"` | - |
| `keyword_tokenizer` | `"NGRAM"` \| `"JIEBA_NGRAM"` | no | default: `"NGRAM"` | - |
| `keyword_fuzzy_enabled` | boolean | no | default: `false` | - |
| `hybrid_semantic_weight` | number | no | min: `0.0`; max: `1.0`; default: `0.5` | - |
| `allow_partial_retrieval` | boolean | no | default: `false` | - |
| `rerank_enabled` | boolean | no | default: `false` | - |
| `rerank_model_ref_id` | string (uuid) \| null | no | - | - |
| `kb_ids` | array<string (uuid)> | no | max items: `64` | - |
| `expected_revision` | integer | yes | min: `1.0` | - |

<a id="schema-agentview"></a>
#### `AgentView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `slug` | string | yes | - | - |
| `description` | string | yes | - | - |
| `avatar` | string \| null | yes | - | - |
| `category` | string \| null | yes | - | - |
| `model_ref` | [RegistryModelRef](#schema-registrymodelref) | yes | - | - |
| `model_connection_status` | `"UNVERIFIED"` \| `"VERIFIED"` \| `"FAILED"` | yes | - | - |
| `temperature` | number | yes | - | - |
| `top_p` | number | yes | - | - |
| `max_tokens` | integer | yes | - | - |
| `concurrent_agents` | integer | yes | - | - |
| `system_prompt` | string | yes | - | - |
| `welcome_message` | string | yes | - | - |
| `suggested_questions` | array<string> | yes | - | - |
| `allow_uploads` | boolean | yes | - | - |
| `retrieval_top_k` | integer | yes | - | - |
| `score_threshold` | number | yes | - | - |
| `embedding_space_thresholds` | object<string, number> | no | - | - |
| `show_citations` | boolean | yes | - | - |
| `restrict_to_kb` | boolean | yes | - | - |
| `query_rewrite_enabled` | boolean | yes | - | - |
| `retrieval_mode` | `"DENSE"` \| `"KEYWORD"` \| `"HYBRID"` | yes | - | - |
| `keyword_algorithm` | `"BM25"` | yes | - | - |
| `keyword_tokenizer` | `"NGRAM"` \| `"JIEBA_NGRAM"` | yes | - | - |
| `keyword_fuzzy_enabled` | boolean | yes | - | - |
| `hybrid_semantic_weight` | number | yes | - | - |
| `allow_partial_retrieval` | boolean | yes | - | - |
| `rerank_enabled` | boolean | yes | - | - |
| `rerank_model_ref_id` | string (uuid) \| null | yes | - | - |
| `kb_ids` | array<string (uuid)> | no | - | - |
| `config_revision` | integer | yes | - | - |
| `status` | [AgentStatus](#schema-agentstatus) | yes | - | - |
| `created_by` | string | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |
| `published_at` | string (date-time) \| null | yes | - | - |

<a id="schema-apiresponse-agentdashboard"></a>
#### `ApiResponse_AgentDashboard_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [AgentDashboard](#schema-agentdashboard) | yes | - | - |

<a id="schema-apiresponse-agenthubapikeycreated"></a>
#### `ApiResponse_AgentHubApiKeyCreated_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [AgentHubApiKeyCreated](#schema-agenthubapikeycreated) | yes | - | - |

<a id="schema-apiresponse-agentkeycreated"></a>
#### `ApiResponse_AgentKeyCreated_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [AgentKeyCreated](#schema-agentkeycreated) | yes | - | - |

<a id="schema-apiresponse-agentkeysecret"></a>
#### `ApiResponse_AgentKeySecret_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [AgentKeySecret](#schema-agentkeysecret) | yes | - | - |

<a id="schema-apiresponse-agentview"></a>
#### `ApiResponse_AgentView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [AgentView](#schema-agentview) | yes | - | - |

<a id="schema-apiresponse-documentrevisionview"></a>
#### `ApiResponse_DocumentRevisionView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [DocumentRevisionView](#schema-documentrevisionview) | yes | - | - |

<a id="schema-apiresponse-documentuploadresult"></a>
#### `ApiResponse_DocumentUploadResult_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [DocumentUploadResult](#schema-documentuploadresult) | yes | - | - |

<a id="schema-apiresponse-knowledgebaseview"></a>
#### `ApiResponse_KnowledgeBaseView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [KnowledgeBaseView](#schema-knowledgebaseview) | yes | - | - |

<a id="schema-apiresponse-knowledgedashboard"></a>
#### `ApiResponse_KnowledgeDashboard_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [KnowledgeDashboard](#schema-knowledgedashboard) | yes | - | - |

<a id="schema-apiresponse-modelcatalogitem"></a>
#### `ApiResponse_ModelCatalogItem_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [ModelCatalogItem](#schema-modelcatalogitem) | yes | - | - |

<a id="schema-apiresponse-modelrefview"></a>
#### `ApiResponse_ModelRefView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [ModelRefView](#schema-modelrefview) | yes | - | - |

<a id="schema-apiresponse-mspmodelimportview"></a>
#### `ApiResponse_MspModelImportView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [MspModelImportView](#schema-mspmodelimportview) | yes | - | - |

<a id="schema-apiresponse-pageresult-agentview"></a>
#### `ApiResponse_PageResult_AgentView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_AgentView_](#schema-pageresult-agentview) | yes | - | - |

<a id="schema-apiresponse-pageresult-chunkpreview"></a>
#### `ApiResponse_PageResult_ChunkPreview__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_ChunkPreview_](#schema-pageresult-chunkpreview) | yes | - | - |

<a id="schema-apiresponse-pageresult-documentrevisionview"></a>
#### `ApiResponse_PageResult_DocumentRevisionView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_DocumentRevisionView_](#schema-pageresult-documentrevisionview) | yes | - | - |

<a id="schema-apiresponse-pageresult-documentview"></a>
#### `ApiResponse_PageResult_DocumentView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_DocumentView_](#schema-pageresult-documentview) | yes | - | - |

<a id="schema-apiresponse-pageresult-embeddingspaceview"></a>
#### `ApiResponse_PageResult_EmbeddingSpaceView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_EmbeddingSpaceView_](#schema-pageresult-embeddingspaceview) | yes | - | - |

<a id="schema-apiresponse-pageresult-knowledgebaseselection"></a>
#### `ApiResponse_PageResult_KnowledgeBaseSelection__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_KnowledgeBaseSelection_](#schema-pageresult-knowledgebaseselection) | yes | - | - |

<a id="schema-apiresponse-pageresult-retrievalpreview"></a>
#### `ApiResponse_PageResult_RetrievalPreview__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_RetrievalPreview_](#schema-pageresult-retrievalpreview) | yes | - | - |

<a id="schema-apiresponse-pageresult-sessionview"></a>
#### `ApiResponse_PageResult_SessionView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [PageResult_SessionView_](#schema-pageresult-sessionview) | yes | - | - |

<a id="schema-apiresponse-parserpreflightview"></a>
#### `ApiResponse_ParserPreflightView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [ParserPreflightView](#schema-parserpreflightview) | yes | - | - |

<a id="schema-apiresponse-rebuildjobview"></a>
#### `ApiResponse_RebuildJobView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [RebuildJobView](#schema-rebuildjobview) | yes | - | - |

<a id="schema-apiresponse-turnview"></a>
#### `ApiResponse_TurnView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | [TurnView](#schema-turnview) | yes | - | - |

<a id="schema-apiresponse-dict-str-bool"></a>
#### `ApiResponse_dict_str__bool__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | object<string, boolean> | yes | - | - |

<a id="schema-apiresponse-list-agenthubapikeyview"></a>
#### `ApiResponse_list_AgentHubApiKeyView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[AgentHubApiKeyView](#schema-agenthubapikeyview)> | yes | - | - |

<a id="schema-apiresponse-list-agentkeyview"></a>
#### `ApiResponse_list_AgentKeyView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[AgentKeyView](#schema-agentkeyview)> | yes | - | - |

<a id="schema-apiresponse-list-messageview"></a>
#### `ApiResponse_list_MessageView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[MessageView](#schema-messageview)> | yes | - | - |

<a id="schema-apiresponse-list-modelcatalogitem"></a>
#### `ApiResponse_list_ModelCatalogItem__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[ModelCatalogItem](#schema-modelcatalogitem)> | yes | - | - |

<a id="schema-apiresponse-list-modelcredentialview"></a>
#### `ApiResponse_list_ModelCredentialView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[ModelCredentialView](#schema-modelcredentialview)> | yes | - | - |

<a id="schema-apiresponse-list-modelrefrevisionview"></a>
#### `ApiResponse_list_ModelRefRevisionView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[ModelRefRevisionView](#schema-modelrefrevisionview)> | yes | - | - |

<a id="schema-apiresponse-list-modelrefview"></a>
#### `ApiResponse_list_ModelRefView__`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `code` | string | no | default: `"OK"` | - |
| `message` | string | no | default: `"success"` | - |
| `data` | array<[ModelRefView](#schema-modelrefview)> | yes | - | - |

<a id="schema-attachmentref"></a>
#### `AttachmentRef`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `file_id` | string | yes | min length: `1`; max length: `128` | - |
| `name` | string \| null | no | - | - |
| `size_bytes` | integer \| null | no | - | - |
| `mime_type` | string \| null | no | - | - |

<a id="schema-attachmentview"></a>
#### `AttachmentView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `file_id` | string | yes | - | - |
| `name` | string | yes | - | - |
| `size_bytes` | integer | yes | min: `0.0` | - |
| `mime_type` | string | yes | - | - |
| `status` | `"STAGED"` \| `"BOUND"` \| `"EXPIRED"` | yes | - | - |

<a id="schema-body-upload-attachment-agent-hub-openapi-v1-agents-agent-id-files-post"></a>
#### `Body_upload_attachment_agent_hub_openapi_v1_agents__agent_id__files_post`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `file` | string | yes | - | - |

<a id="schema-body-upload-document-agent-hub-api-v1-kbs-kb-id-documents-post"></a>
#### `Body_upload_document_agent_hub_api_v1_kbs__kb_id__documents_post`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `file` | string | yes | - | PDF, image, Office, Markdown, or text document (max 200 MiB) |

<a id="schema-chatcompletionrequest"></a>
#### `ChatCompletionRequest`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `model` | string \| null | no | - | - |
| `messages` | array<[ChatMessageInput](#schema-chatmessageinput)> | yes | min items: `1`; max items: `256` | - |
| `session_id` | string \| null | no | - | - |
| `stream` | boolean | no | default: `true` | - |
| `temperature` | number \| null | no | - | - |
| `top_p` | number \| null | no | - | - |
| `max_tokens` | integer \| null | no | - | - |
| `attachments` | array<[AttachmentRef](#schema-attachmentref)> | no | max items: `16` | - |
| `user` | string \| null | no | - | - |

<a id="schema-chatmessageinput"></a>
#### `ChatMessageInput`

V1 freezes message content as text; attachments use separate refs.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `role` | `"system"` \| `"user"` \| `"assistant"` | yes | - | - |
| `content` | string | yes | min length: `1`; max length: `1000000` | - |

<a id="schema-chunkpreview"></a>
#### `ChunkPreview`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | - | - |
| `document_id` | string (uuid) | yes | - | - |
| `document_name` | string | yes | - | - |
| `token_count` | integer | yes | min: `1.0` | - |
| `text` | string | yes | - | - |
| `page_no` | integer \| null | no | - | - |
| `heading_path` | array<string> | no | - | - |

<a id="schema-distribution"></a>
#### `Distribution`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `samples` | integer | no | default: `0` | - |
| `avg_ms` | number \| null | no | - | - |
| `p50_ms` | number \| null | no | - | - |
| `p95_ms` | number \| null | no | - | - |

<a id="schema-documentpublishstate"></a>
#### `DocumentPublishState`

Type: `"ACTIVE"` | `"SWITCHING"` | `"DELETING"`

<a id="schema-documentrevisionview"></a>
#### `DocumentRevisionView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `doc_id` | string (uuid) | yes | - | - |
| `revision_no` | integer | yes | - | - |
| `status` | [RevisionStatus](#schema-revisionstatus) | yes | - | - |
| `raw_sha256` | string | yes | - | - |
| `parsed_sha256` | string \| null | yes | - | - |
| `chunk_sha256` | string \| null | yes | - | - |
| `parser_revision` | string \| null | yes | - | - |
| `embedding_space_id` | string (uuid) \| null | yes | - | - |
| `embedding_model_revision` | string \| null | yes | - | - |
| `embedding_dim` | integer \| null | yes | - | - |
| `chunk_count` | integer | yes | - | - |
| `fail_reason` | string \| null | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |

<a id="schema-documentstatus"></a>
#### `DocumentStatus`

Type: `"QUEUED"` | `"PROCESSING"` | `"READY"` | `"FAILED"`

<a id="schema-documentuploadresult"></a>
#### `DocumentUploadResult`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `document` | [DocumentView](#schema-documentview) | yes | - | - |
| `revision` | [DocumentRevisionView](#schema-documentrevisionview) | yes | - | - |

<a id="schema-documentview"></a>
#### `DocumentView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `kb_id` | string (uuid) | yes | - | - |
| `file_name` | string | yes | - | - |
| `file_type` | string | yes | - | - |
| `size_bytes` | integer | yes | - | - |
| `page_count` | integer \| null | yes | - | - |
| `current_revision_id` | string (uuid) \| null | yes | - | - |
| `publish_state` | [DocumentPublishState](#schema-documentpublishstate) | yes | - | - |
| `chunk_count` | integer | yes | - | - |
| `status` | [DocumentStatus](#schema-documentstatus) | yes | - | - |
| `progress` | integer | yes | - | - |
| `fail_reason` | string \| null | yes | - | - |
| `uploaded_by` | string | yes | - | - |
| `uploaded_at` | string (date-time) | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |
| `latest_revision_id` | string (uuid) \| null | no | - | - |
| `latest_revision_status` | [RevisionStatus](#schema-revisionstatus) \| null | no | - | - |

<a id="schema-embeddingspacestatus"></a>
#### `EmbeddingSpaceStatus`

Type: `"BUILDING"` | `"READY"` | `"FAILED"` | `"DELETING"`

<a id="schema-embeddingspaceview"></a>
#### `EmbeddingSpaceView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `model_ref_id` | string (uuid) | yes | - | - |
| `model_revision` | string | yes | - | - |
| `dimension` | integer | yes | - | - |
| `distance` | string | yes | - | - |
| `normalize` | boolean | yes | - | - |
| `schema_version` | integer | yes | - | - |
| `capacity_profile` | string | yes | - | - |
| `status` | [EmbeddingSpaceStatus](#schema-embeddingspacestatus) | yes | - | - |

<a id="schema-httpvalidationerror"></a>
#### `HTTPValidationError`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `detail` | array<[ValidationError](#schema-validationerror)> | no | - | - |

<a id="schema-knowledgebasecreate"></a>
#### `KnowledgeBaseCreate`

Create a KB against an existing authoritative embedding space.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `4000`; default: `""` | - |
| `parser_ref` | [ParserProfile](#schema-parserprofile) | no | - | - |
| `embedding_space_id` | string (uuid) \| null | no | - | - |
| `index_mode` | `"HYBRID"` \| `"KEYWORD"` | no | default: `"HYBRID"` | - |
| `chunk_size` | integer | no | min: `64.0`; max: `8192.0`; default: `512` | - |
| `chunk_overlap` | integer | no | min: `0.0`; max: `4096.0`; default: `64` | - |
| `split_strategy` | string | no | min length: `1`; max length: `64`; default: `"heading"` | - |
| `ocr_enabled` | boolean | no | default: `true` | - |
| `table_extract_enabled` | boolean | no | default: `true` | - |
| `capacity_profile` | string | no | min length: `1`; max length: `64`; default: `"default"` | - |

<a id="schema-knowledgebaseselection"></a>
#### `KnowledgeBaseSelection`

Small DTO consumed by Agent create/edit screens.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `status` | [KnowledgeBaseStatus](#schema-knowledgebasestatus) | yes | - | - |
| `embedding_space` | string (uuid) \| null | yes | - | - |
| `keyword_tokenizers` | array<`"NGRAM"` \| `"JIEBA_NGRAM"`> \| null | no | - | - |
| `doc_count` | integer | yes | - | - |
| `chunk_count` | integer | yes | - | - |

<a id="schema-knowledgebasestatus"></a>
#### `KnowledgeBaseStatus`

Type: `"READY"` | `"BUILDING"` | `"SWITCHING"` | `"DELETING"` | `"FAILED"`

<a id="schema-knowledgebaseupdate"></a>
#### `KnowledgeBaseUpdate`

Mutable metadata only; parser or embedding changes require a rebuild.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | yes | min length: `1`; max length: `128` | - |
| `description` | string | no | max length: `4000`; default: `""` | - |
| `expected_updated_at` | string (date-time) | yes | - | - |

<a id="schema-knowledgebaseview"></a>
#### `KnowledgeBaseView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `name` | string | yes | - | - |
| `description` | string | yes | - | - |
| `parser_ref` | object | yes | - | - |
| `embedding_space_id` | string (uuid) \| null | yes | - | - |
| `embedding_model_revision` | string \| null | yes | - | - |
| `embedding_dim` | integer \| null | yes | - | - |
| `generation` | integer | yes | - | - |
| `chunk_size` | integer | yes | - | - |
| `chunk_overlap` | integer | yes | - | - |
| `split_strategy` | string | yes | - | - |
| `ocr_enabled` | boolean | yes | - | - |
| `table_extract_enabled` | boolean | yes | - | - |
| `capacity_profile` | string | yes | - | - |
| `status` | [KnowledgeBaseStatus](#schema-knowledgebasestatus) | yes | - | - |
| `doc_count` | integer | yes | - | - |
| `chunk_count` | integer | yes | - | - |
| `total_size` | integer | yes | - | - |
| `created_by` | string | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |
| `active_rebuild` | [ActiveRebuildSummary](#schema-activerebuildsummary) \| null | no | - | - |

<a id="schema-knowledgedashboard"></a>
#### `KnowledgeDashboard`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `window` | `"1h"` \| `"24h"` \| `"7d"` | yes | - | - |
| `start_at` | string (date-time) | yes | - | - |
| `end_at` | string (date-time) | yes | - | - |
| `bucket_seconds` | integer | yes | - | - |
| `summary` | [KnowledgeSummary](#schema-knowledgesummary) | yes | - | - |
| `trend` | array<[RetrievalTrend](#schema-retrievaltrend)> | yes | - | - |
| `knowledge_bases` | array<[KnowledgeState](#schema-knowledgestate)> | yes | - | - |
| `total` | integer | yes | - | - |
| `page` | integer | yes | - | - |
| `page_size` | integer | yes | - | - |

<a id="schema-knowledgestate"></a>
#### `KnowledgeState`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `kb_id` | string | yes | - | - |
| `name` | string | yes | - | - |
| `status` | string | yes | - | - |
| `documents` | integer | yes | - | - |
| `chunks` | integer | yes | - | - |
| `total_size_bytes` | integer | yes | - | - |
| `queued` | integer | yes | - | - |
| `processing` | integer | yes | - | - |
| `failed` | integer | yes | - | - |

<a id="schema-knowledgesummary"></a>
#### `KnowledgeSummary`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `knowledge_bases` | integer | no | default: `0` | - |
| `documents` | integer | no | default: `0` | - |
| `chunks` | integer | no | default: `0` | - |
| `total_size_bytes` | integer | no | default: `0` | - |
| `queued_documents` | integer | no | default: `0` | - |
| `processing_documents` | integer | no | default: `0` | - |
| `failed_documents` | integer | no | default: `0` | - |
| `retrieval_requests` | integer | no | default: `0` | - |
| `retrieval_failed` | integer | no | default: `0` | - |
| `retrieval_partial` | integer | no | default: `0` | - |
| `retrieval_empty` | integer | no | default: `0` | - |
| `empty_rate` | number \| null | no | - | - |
| `retrieval_latency` | [Distribution](#schema-distribution) | no | - | - |

<a id="schema-messageview"></a>
#### `MessageView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | - | - |
| `turn_no` | integer | yes | min: `1.0` | - |
| `role` | `"user"` \| `"assistant"` \| `"system"` | yes | - | - |
| `content` | string | yes | - | - |
| `attachments` | array<object> | yes | - | - |
| `citations` | array<object> | yes | - | - |
| `retrieval` | object \| null | no | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-modelcatalogitem"></a>
#### `ModelCatalogItem`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `source` | string | no | - | Deployment integration source identifier. |
| `service_id` | string | yes | - | - |
| `name` | string | yes | - | - |
| `model_name` | string | yes | - | - |
| `model_type` | string | yes | - | - |
| `capabilities` | array<string> | no | - | - |
| `status` | string | yes | - | - |
| `context_window_tokens` | integer \| null | no | - | - |
| `base_url` | string \| null | no | - | - |

<a id="schema-modelcredentialrotate"></a>
#### `ModelCredentialRotate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `api_key` | string (password) \| null | yes | - | - |
| `expected_revision` | integer | yes | min: `1.0` | - |

<a id="schema-modelcredentialview"></a>
#### `ModelCredentialView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `generation` | integer | yes | - | - |
| `status` | string | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-modellifecycleaction"></a>
#### `ModelLifecycleAction`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `action` | `"DISABLE"` \| `"RETEST"` | yes | - | - |
| `expected_revision` | integer | yes | min: `1.0` | - |

<a id="schema-modelrefcreate"></a>
#### `ModelRefCreate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `ref_id` | string | no | min length: `1`; max length: `64`; pattern: `^[A-Za-z0-9][A-Za-z0-9._-]*$`; default: `""` | - |
| `display_name` | string | no | min length: `1`; max length: `128`; default: `""` | - |
| `model_type` | `"CHAT"` \| `"EMBEDDING"` \| `"RERANK"` | yes | - | - |
| `capabilities` | array<string> | no | max items: `32` | - |
| `base_url` | string (uri) | yes | min length: `1` | - |
| `model_name` | string | yes | min length: `1`; max length: `256` | - |
| `declared_revision` | string | no | min length: `1`; max length: `256`; default: `"default"` | - |
| `api_key` | string (password) \| null | no | - | - |
| `normalize` | boolean \| null | no | - | - |
| `context_window_tokens` | integer | no | min: `2048.0`; max: `2000000.0`; default: `32768` | - |

<a id="schema-modelrefrevisionview"></a>
#### `ModelRefRevisionView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `protocol` | string | yes | - | - |
| `base_url` | string | yes | - | - |
| `model_name` | string | yes | - | - |
| `declared_revision` | string | yes | - | - |
| `context_window_tokens` | integer | no | default: `32768` | - |
| `server_model_revision` | string \| null | yes | - | - |
| `verified_embedding_dim` | integer \| null | yes | - | - |
| `verified_normalize` | boolean \| null | yes | - | - |
| `status` | string | yes | - | - |
| `reason_code` | string \| null | yes | - | - |
| `verified_at` | string (date-time) \| null | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |

<a id="schema-modelrefupdate"></a>
#### `ModelRefUpdate`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `display_name` | string \| null | no | - | - |
| `capabilities` | array<string> \| null | no | - | - |
| `expected_revision` | integer | yes | min: `1.0` | - |

<a id="schema-modelrefview"></a>
#### `ModelRefView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `ref_id` | string | yes | - | - |
| `display_name` | string | yes | - | - |
| `model_type` | string | yes | - | - |
| `capabilities` | array<string> | yes | - | - |
| `status` | string | yes | - | - |
| `revision` | integer | yes | - | - |
| `active_revision` | [ModelRefRevisionView](#schema-modelrefrevisionview) \| null | no | - | - |
| `candidate_revision_id` | string (uuid) \| null | no | - | - |
| `active_credential_generation` | integer \| null | no | - | - |
| `credentials` | array<[ModelCredentialView](#schema-modelcredentialview)> | no | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |

<a id="schema-modelrevisioncreate"></a>
#### `ModelRevisionCreate`

New endpoint/model revision for a CHAT or RERANK ref.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `base_url` | string (uri) | yes | min length: `1` | - |
| `model_name` | string | yes | min length: `1`; max length: `256` | - |
| `declared_revision` | string | yes | min length: `1`; max length: `256` | - |
| `context_window_tokens` | integer | no | min: `2048.0`; max: `2000000.0`; default: `32768` | - |
| `expected_revision` | integer | yes | min: `1.0` | - |

<a id="schema-mspmodelimport"></a>
#### `MspModelImport`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `service_id` | string | yes | min length: `1`; max length: `128` | - |
| `model_type` | `"CHAT"` \| `"EMBEDDING"` \| `"RERANK"` | yes | - | - |
| `api_key` | string (password) \| null | no | - | - |

<a id="schema-mspmodelimportview"></a>
#### `MspModelImportView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `model` | [ModelRefView](#schema-modelrefview) | yes | - | - |
| `embedding_space` | [EmbeddingSpaceView](#schema-embeddingspaceview) \| null | no | - | - |

<a id="schema-pageresult-agentview"></a>
#### `PageResult_AgentView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[AgentView](#schema-agentview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-chunkpreview"></a>
#### `PageResult_ChunkPreview_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[ChunkPreview](#schema-chunkpreview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-documentrevisionview"></a>
#### `PageResult_DocumentRevisionView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[DocumentRevisionView](#schema-documentrevisionview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-documentview"></a>
#### `PageResult_DocumentView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[DocumentView](#schema-documentview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-embeddingspaceview"></a>
#### `PageResult_EmbeddingSpaceView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[EmbeddingSpaceView](#schema-embeddingspaceview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-knowledgebaseselection"></a>
#### `PageResult_KnowledgeBaseSelection_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[KnowledgeBaseSelection](#schema-knowledgebaseselection)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-retrievalpreview"></a>
#### `PageResult_RetrievalPreview_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[RetrievalPreview](#schema-retrievalpreview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-pageresult-sessionview"></a>
#### `PageResult_SessionView_`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `items` | array<[SessionView](#schema-sessionview)> | yes | - | - |
| `total` | integer | yes | min: `0.0` | - |
| `page` | integer | yes | min: `1.0` | - |
| `pageSize` | integer | yes | min: `1.0` | - |

<a id="schema-parserpreflightrequest"></a>
#### `ParserPreflightRequest`

Parser choice to validate before a knowledge base is persisted.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `parser_ref` | [ParserProfile](#schema-parserprofile) | no | - | - |

<a id="schema-parserpreflightview"></a>
#### `ParserPreflightView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `ready` | boolean | yes | - | - |
| `required` | [ParserResourceView](#schema-parserresourceview) | yes | - | - |
| `schedulable_node_count` | integer | yes | min: `0.0` | - |
| `fit_node_count` | integer | yes | min: `0.0` | - |
| `shortages` | array<`"CPU"` \| `"MEMORY"` \| `"GPU"` \| `"PLACEMENT"`> | no | default: `[]` | - |
| `message` | string | yes | - | - |
| `checked_at` | string (date-time) | yes | - | - |

<a id="schema-parserprofile"></a>
#### `ParserProfile`

Server-owned MinerU parser selection with no inline endpoint or secret.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `schema_version` | `1` | no | default: `1` | - |
| `engine` | `"mineru"` | no | default: `"mineru"` | - |
| `mode` | `"builtin"` \| `"openai"` | no | default: `"builtin"` | - |
| `backend` | `"hybrid-auto-engine"` \| `"vlm-http-client"` \| `"hybrid-http-client"` | no | default: `"hybrid-auto-engine"` | - |
| `provider_ref` | string \| null | no | - | - |
| `language` | string | no | min length: `1`; max length: `32`; default: `"ch"` | - |
| `parse_method` | `"auto"` \| `"txt"` \| `"ocr"` | no | default: `"auto"` | - |
| `formula_enabled` | boolean | no | default: `true` | - |
| `table_enabled` | boolean | no | default: `true` | - |

<a id="schema-parserresourceview"></a>
#### `ParserResourceView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `cpu_millis` | integer | yes | min: `0.0` | - |
| `memory_bytes` | integer | yes | min: `0.0` | - |
| `gpu_count` | integer | yes | min: `0.0` | - |

<a id="schema-rebuildjobstatus"></a>
#### `RebuildJobStatus`

Whole-KB rebuild lifecycle; BUILDING and CLEANING both block new rebuilds.

Type: `"BUILDING"` | `"CLEANING"` | `"DONE"` | `"FAILED"`

<a id="schema-rebuildjobview"></a>
#### `RebuildJobView`

Full rebuild job detail returned by the rebuild endpoints.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `id` | string (uuid) | yes | - | - |
| `kb_id` | string (uuid) | yes | - | - |
| `status` | [RebuildJobStatus](#schema-rebuildjobstatus) | yes | - | - |
| `from_generation` | integer | yes | - | - |
| `to_generation` | integer | yes | - | - |
| `target_embedding_space_id` | string (uuid) \| null | yes | - | - |
| `target_collection` | string | yes | - | - |
| `params` | object | yes | - | - |
| `document_total` | integer | yes | - | - |
| `documents_ready` | integer | yes | - | - |
| `documents_failed` | integer | yes | - | - |
| `error` | string \| null | yes | - | - |
| `created_by` | string | yes | - | - |
| `created_at` | string (date-time) | yes | - | - |
| `updated_at` | string (date-time) | yes | - | - |
| `completed_at` | string (date-time) \| null | yes | - | - |

<a id="schema-rebuildrequest"></a>
#### `RebuildRequest`

Blue-green rebuild parameters; omitted fields keep the KB's current value.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `embedding_space_id` | string (uuid) \| null | no | - | - |
| `chunk_size` | integer \| null | no | - | - |
| `chunk_overlap` | integer \| null | no | - | - |
| `split_strategy` | string \| null | no | - | - |
| `ocr_enabled` | boolean \| null | no | - | - |
| `table_extract_enabled` | boolean \| null | no | - | - |
| `parser_ref` | [ParserProfile](#schema-parserprofile) \| null | no | - | - |

<a id="schema-registrymodelref"></a>
#### `RegistryModelRef`

Binding to a platform-owned registry model by its stable id. The Agent stores only the stable reference; endpoint, revision and secret stay in the registry. The revision pin lands at publish time and freezes the Agent's model identity.

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `source` | `"REGISTRY"` | yes | - | - |
| `model_ref_id` | string (uuid) | yes | - | - |

<a id="schema-retrievalpreview"></a>
#### `RetrievalPreview`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `chunk_id` | string | yes | - | - |
| `document_name` | string | yes | - | - |
| `text` | string | yes | - | - |
| `score` | number | yes | - | - |
| `page_no` | integer \| null | no | - | - |

<a id="schema-retrievaltestrequest"></a>
#### `RetrievalTestRequest`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | yes | min length: `1`; max length: `32768` | - |
| `top_k` | integer | no | min: `1.0`; max: `100.0`; default: `8` | - |
| `threshold` | number | no | min: `-1.0`; max: `1.0`; default: `0.0` | - |
| `retrieval_mode` | `"DENSE"` \| `"KEYWORD"` \| `"HYBRID"` | no | default: `"DENSE"` | - |

<a id="schema-retrievaltrend"></a>
#### `RetrievalTrend`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `at` | string (date-time) | yes | - | - |
| `requests` | integer | no | default: `0` | - |
| `failed` | integer | no | default: `0` | - |
| `empty` | integer | no | default: `0` | - |

<a id="schema-revisionstatus"></a>
#### `RevisionStatus`

Type: `"QUEUED"` | `"PARSING"` | `"CHUNKING"` | `"EMBEDDING"` | `"READY"` | `"PUBLISHING"` | `"ACTIVE"` | `"RETIRED"` | `"FAILED"`

<a id="schema-sessionstatus"></a>
#### `SessionStatus`

Type: `"ACTIVE"` | `"IDLE"` | `"CLOSED"`

<a id="schema-sessionview"></a>
#### `SessionView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `session_id` | string | yes | - | - |
| `agent_id` | string | yes | - | - |
| `end_user` | string \| null | yes | - | - |
| `channel` | string | yes | - | - |
| `status` | `"ACTIVE"` \| `"IDLE"` \| `"CLOSED"` | yes | - | - |
| `message_count` | integer | yes | min: `0.0` | - |
| `total_tokens` | integer | yes | min: `0.0` | - |
| `active_turn_id` | string \| null | no | - | - |
| `started_at` | string (date-time) | yes | - | - |
| `last_active_at` | string (date-time) | yes | - | - |

<a id="schema-turnfailure"></a>
#### `TurnFailure`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `turn_id` | string | yes | - | - |
| `session_id` | string | yes | - | - |
| `agent_id` | string | yes | - | - |
| `agent_name` | string | yes | - | - |
| `status` | string | yes | - | - |
| `error_code` | string \| null | yes | - | - |
| `started_at` | string (date-time) | yes | - | - |
| `duration_ms` | number \| null | yes | - | - |

<a id="schema-turnview"></a>
#### `TurnView`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `turn_id` | string | yes | - | - |
| `session_id` | string | yes | - | - |
| `turn_no` | integer | yes | min: `1.0` | - |
| `status` | `"RUNNING"` \| `"DONE"` \| `"FAILED"` \| `"INTERRUPTED"` | yes | - | - |
| `final_text` | string \| null | yes | - | - |
| `citations` | array<object> | yes | - | - |
| `fail_code` | string \| null | yes | - | - |
| `started_at` | string (date-time) | yes | - | - |
| `ended_at` | string (date-time) \| null | yes | - | - |

<a id="schema-validationerror"></a>
#### `ValidationError`

| Field | Type | Required | Constraints/default | Description |
| --- | --- | --- | --- | --- |
| `loc` | array<string \| integer> | yes | - | - |
| `msg` | string | yes | - | - |
| `type` | string | yes | - | - |
| `input` | object | no | - | - |
| `ctx` | object | no | - | - |

<!-- END GENERATED METHOD REFERENCE -->
