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
• Install
• Management Client
• Knowledge-base Workflow
• Application Client
• Async Usage
• CLI
• Errors
• Naming and Return Values
• Module Overview
• 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

python -m pip install smart-agenthub

Pin a version for reproducible deployments:

python -m pip install smart-agenthub==0.1.1

Management Client

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

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

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

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

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.

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.

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:

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.

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.

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>
client.api_keys.create(*, body)	Create Api Key	body: AgentHubApiKeyCreate (required)	AgentHubApiKeyCreated
client.api_keys.revoke(key_id)	Revoke Api Key	path: key_id (required); body: none	no value

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_AgentHubApiKeyView__	Successful Response

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

SDK response

Returns AgentHubApiKeyCreated.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_AgentHubApiKeyCreated_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

Models

SDK method	Purpose	Request	SDK response
client.models.catalog()	List Models	body: none	array<ModelCatalogItem>
client.models.import_msp(*, body)	Import Msp Model	body: MspModelImport (required)	MspModelImportView
client.models.get_msp(service_id)	Msp Model Detail	path: service_id (required); body: none	ModelCatalogItem
client.models.list(*, status_filter=None)	List Registry	query: status_filter; body: none	array<ModelRefView>
client.models.create(*, body)	Create Registry	body: ModelRefCreate (required)	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
client.models.update(model_ref_id, *, body)	Update Registry	path: model_ref_id (required); body: ModelRefUpdate (required)	ModelRefView
client.models.change_lifecycle(model_ref_id, *, body)	Registry Lifecycle	path: model_ref_id (required); body: ModelLifecycleAction (required)	ModelRefView

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_ModelCatalogItem__	Successful Response

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

SDK response

Returns MspModelImportView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_MspModelImportView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ModelCatalogItem_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_ModelRefView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ModelRefView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ModelRefView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ModelRefView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	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>
client.model_revisions.create(model_ref_id, *, body)	Add Registry Revision	path: model_ref_id (required); body: ModelRevisionCreate (required)	ModelRefView

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_ModelRefRevisionView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ModelRefView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	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>
client.model_credentials.rotate(model_ref_id, *, body)	Rotate Registry Credential	path: model_ref_id (required); body: ModelCredentialRotate (required)	ModelRefView

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_ModelCredentialView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ModelRefView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ModelRefView_	Successful Response
422	application/json	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_

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 | null	no	-

Request body

No request body.

SDK response

Returns PageResult_EmbeddingSpaceView_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_EmbeddingSpaceView__	Successful Response
422	application/json	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_
client.knowledge_bases.create(*, body)	Create Knowledge Base	body: KnowledgeBaseCreate (required)	KnowledgeBaseView
client.knowledge_bases.parser_preflight(*, body)	Preflight Knowledge Base Parser	body: ParserPreflightRequest (required)	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
client.knowledge_bases.update(kb_id, *, body)	Update Knowledge Base	path: kb_id (required); body: KnowledgeBaseUpdate (required)	KnowledgeBaseView
client.knowledge_bases.list_chunks(kb_id)	List Chunks	path: kb_id (required); body: none	PageResult_ChunkPreview_
client.knowledge_bases.latest_rebuild(kb_id)	Get Latest Rebuild Job	path: kb_id (required); body: none	RebuildJobView
client.knowledge_bases.rebuild(kb_id, *, body=None, idempotency_key)	Rebuild Knowledge Base	path: kb_id (required); header: Idempotency-Key (required); body: RebuildRequest | null (optional)	RebuildJobView
client.knowledge_bases.test_retrieval(kb_id, *, body)	Retrieval Test	path: kb_id (required); body: RetrievalTestRequest (required)	PageResult_RetrievalPreview_

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 | null	no	-
query	include_index_capabilities	include_index_capabilities	boolean	no	default: false

Request body

No request body.

SDK response

Returns PageResult_KnowledgeBaseSelection_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_KnowledgeBaseSelection__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns KnowledgeBaseView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_KnowledgeBaseView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns ParserPreflightView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_ParserPreflightView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_KnowledgeBaseView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns KnowledgeBaseView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_KnowledgeBaseView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_ChunkPreview__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_RebuildJobView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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 | null

SDK response

Returns RebuildJobView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
202	application/json	ApiResponse_RebuildJobView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns PageResult_RetrievalPreview_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_RetrievalPreview__	Successful Response
422	application/json	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
client.documents.list_revisions(document_id)	List Document Revisions	path: document_id (required); body: none	PageResult_DocumentRevisionView_
client.documents.get_revision(document_id, revision_id)	Get Document Revision	path: document_id (required), revision_id (required); body: none	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_
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 (required)	DocumentUploadResult

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	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
202	application/json	ApiResponse_DocumentUploadResult_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_DocumentRevisionView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_DocumentRevisionView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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 | null	no	-

Request body

No request body.

SDK response

Returns PageResult_DocumentView_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_DocumentView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns DocumentUploadResult.

HTTP response bodies

HTTP	Content-Type	Schema	Description
202	application/json	ApiResponse_DocumentUploadResult_	Successful Response
422	application/json	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_
client.agents.create(*, body)	Create Agent	body: AgentCreate (required)	AgentView
client.agents.preflight(*, body)	Validate create-and-publish readiness without writing an Agent row.	body: 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
client.agents.update(agent_id, *, body)	Update Agent	path: agent_id (required); body: AgentUpdate (required)	AgentView
client.agents.offline(agent_id)	Offline Agent	path: agent_id (required); body: none	AgentView
client.agents.publish(agent_id)	Publish Agent	path: agent_id (required); body: none	AgentView

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 | null	no	-

Request body

No request body.

SDK response

Returns PageResult_AgentView_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_AgentView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns AgentView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_AgentView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns object<string, boolean>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_dict_str__bool__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns AgentView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentView_	Successful Response
422	application/json	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>
client.agent_keys.create(agent_id, *, body)	Create Agent Key	path: agent_id (required); body: AgentKeyCreate (required)	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

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_AgentKeyView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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

SDK response

Returns AgentKeyCreated.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	ApiResponse_AgentKeyCreated_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentKeySecret_	Successful Response
422	application/json	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_
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>

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 | 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_.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_PageResult_SessionView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_MessageView__	Successful Response
422	application/json	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
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

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_AgentDashboard_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_KnowledgeDashboard_	Successful Response
422	application/json	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 (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 (required)	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>
agent.get_turn(turn_id)	Get Turn	path: turn_id (required); body: none	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

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

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	Validation Error

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

SDK response

Returns AttachmentView.

HTTP response bodies

HTTP	Content-Type	Schema	Description
201	application/json	AttachmentView	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

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>.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_list_MessageView__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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.

HTTP response bodies

HTTP	Content-Type	Schema	Description
200	application/json	ApiResponse_TurnView_	Successful Response
422	application/json	HTTPValidationError	Validation Error

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__	Successful Response
422	application/json	HTTPValidationError	Validation Error

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	Validation Error

Payload Schema Reference

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

ActiveRebuildSummary

Compact progress view embedded in the KB detail response.

Field	Type	Required	Constraints/default	Description
id	string (uuid)	yes	-	-
status	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	-	-

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	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	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	-

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	yes	-	-
trend	array<AgentTrend>	yes	-	-
recent_failures	array<TurnFailure>	yes	-	-

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	-	-

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	-	-

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	-	-

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	-	-

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	yes	-	-
expires_at	string (date-time) | null	yes	-	-

AgentKeySecret

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

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	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	-	-

AgentStatus

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

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	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	no	-	-

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	-

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	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	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	-

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	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	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	yes	-	-
created_by	string	yes	-	-
created_at	string (date-time)	yes	-	-
updated_at	string (date-time)	yes	-	-
published_at	string (date-time) | null	yes	-	-

ApiResponse_AgentDashboard_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	AgentDashboard	yes	-	-

ApiResponse_AgentHubApiKeyCreated_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	AgentHubApiKeyCreated	yes	-	-

ApiResponse_AgentKeyCreated_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	AgentKeyCreated	yes	-	-

ApiResponse_AgentKeySecret_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	AgentKeySecret	yes	-	-

ApiResponse_AgentView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	AgentView	yes	-	-

ApiResponse_DocumentRevisionView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	DocumentRevisionView	yes	-	-

ApiResponse_DocumentUploadResult_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	DocumentUploadResult	yes	-	-

ApiResponse_KnowledgeBaseView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	KnowledgeBaseView	yes	-	-

ApiResponse_KnowledgeDashboard_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	KnowledgeDashboard	yes	-	-

ApiResponse_ModelCatalogItem_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	ModelCatalogItem	yes	-	-

ApiResponse_ModelRefView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	ModelRefView	yes	-	-

ApiResponse_MspModelImportView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	MspModelImportView	yes	-	-

ApiResponse_PageResult_AgentView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_AgentView_	yes	-	-

ApiResponse_PageResult_ChunkPreview__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_ChunkPreview_	yes	-	-

ApiResponse_PageResult_DocumentRevisionView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_DocumentRevisionView_	yes	-	-

ApiResponse_PageResult_DocumentView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_DocumentView_	yes	-	-

ApiResponse_PageResult_EmbeddingSpaceView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_EmbeddingSpaceView_	yes	-	-

ApiResponse_PageResult_KnowledgeBaseSelection__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_KnowledgeBaseSelection_	yes	-	-

ApiResponse_PageResult_RetrievalPreview__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_RetrievalPreview_	yes	-	-

ApiResponse_PageResult_SessionView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	PageResult_SessionView_	yes	-	-

ApiResponse_ParserPreflightView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	ParserPreflightView	yes	-	-

ApiResponse_RebuildJobView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	RebuildJobView	yes	-	-

ApiResponse_TurnView_

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	TurnView	yes	-	-

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	-	-

ApiResponse_list_AgentHubApiKeyView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<AgentHubApiKeyView>	yes	-	-

ApiResponse_list_AgentKeyView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<AgentKeyView>	yes	-	-

ApiResponse_list_MessageView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<MessageView>	yes	-	-

ApiResponse_list_ModelCatalogItem__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<ModelCatalogItem>	yes	-	-

ApiResponse_list_ModelCredentialView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<ModelCredentialView>	yes	-	-

ApiResponse_list_ModelRefRevisionView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<ModelRefRevisionView>	yes	-	-

ApiResponse_list_ModelRefView__

Field	Type	Required	Constraints/default	Description
code	string	no	default: "OK"	-
message	string	no	default: "success"	-
data	array<ModelRefView>	yes	-	-

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	-	-

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	-	-

Body_upload_attachment_agent_hub_openapi_v1_agents__agent_id__files_post

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

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)

ChatCompletionRequest

Field	Type	Required	Constraints/default	Description
model	string | null	no	-	-
messages	array<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>	no	max items: 16	-
user	string | null	no	-	-

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	-

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	no	-	-

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	-	-

DocumentPublishState

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

DocumentRevisionView

Field	Type	Required	Constraints/default	Description
id	string (uuid)	yes	-	-
doc_id	string (uuid)	yes	-	-
revision_no	integer	yes	-	-
status	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	-	-

DocumentStatus

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

DocumentUploadResult

Field	Type	Required	Constraints/default	Description
document	DocumentView	yes	-	-
revision	DocumentRevisionView	yes	-	-

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	yes	-	-
chunk_count	integer	yes	-	-
status	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 | null	no	-	-

EmbeddingSpaceStatus

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

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	yes	-	-

HTTPValidationError

Field	Type	Required	Constraints/default	Description
detail	array<ValidationError>	no	-	-

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	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"	-

KnowledgeBaseSelection

Small DTO consumed by Agent create/edit screens.

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

KnowledgeBaseStatus

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

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	-	-

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	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 | null	no	-	-

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	yes	-	-
trend	array<RetrievalTrend>	yes	-	-
knowledge_bases	array<KnowledgeState>	yes	-	-
total	integer	yes	-	-
page	integer	yes	-	-
page_size	integer	yes	-	-

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	-	-

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	no	-	-

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	yes	-	-
citations	array	yes	-	-
retrieval	object | null	no	-	-
created_at	string (date-time)	yes	-	-

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	no	-	-
status	string	yes	-	-
context_window_tokens	integer | null	no	-	-
base_url	string | null	no	-	-

ModelCredentialRotate

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

ModelCredentialView

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

ModelLifecycleAction

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

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	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	-

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	-	-

ModelRefUpdate

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

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	yes	-	-
status	string	yes	-	-
revision	integer	yes	-	-
active_revision	ModelRefRevisionView | null	no	-	-
candidate_revision_id	string (uuid) | null	no	-	-
active_credential_generation	integer | null	no	-	-
credentials	array<ModelCredentialView>	no	-	-
created_at	string (date-time)	yes	-	-
updated_at	string (date-time)	yes	-	-

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	-

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	-	-

MspModelImportView

Field	Type	Required	Constraints/default	Description
model	ModelRefView	yes	-	-
embedding_space	EmbeddingSpaceView | null	no	-	-

PageResult_AgentView_

Field	Type	Required	Constraints/default	Description
items	array<AgentView>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_ChunkPreview_

Field	Type	Required	Constraints/default	Description
items	array<ChunkPreview>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_DocumentRevisionView_

Field	Type	Required	Constraints/default	Description
items	array<DocumentRevisionView>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_DocumentView_

Field	Type	Required	Constraints/default	Description
items	array<DocumentView>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_EmbeddingSpaceView_

Field	Type	Required	Constraints/default	Description
items	array<EmbeddingSpaceView>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_KnowledgeBaseSelection_

Field	Type	Required	Constraints/default	Description
items	array<KnowledgeBaseSelection>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_RetrievalPreview_

Field	Type	Required	Constraints/default	Description
items	array<RetrievalPreview>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

PageResult_SessionView_

Field	Type	Required	Constraints/default	Description
items	array<SessionView>	yes	-	-
total	integer	yes	min: 0.0	-
page	integer	yes	min: 1.0	-
pageSize	integer	yes	min: 1.0	-

ParserPreflightRequest

Parser choice to validate before a knowledge base is persisted.

Field	Type	Required	Constraints/default	Description
parser_ref	ParserProfile	no	-	-

ParserPreflightView

Field	Type	Required	Constraints/default	Description
ready	boolean	yes	-	-
required	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	-	-

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	-

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	-

RebuildJobStatus

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

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

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	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	-	-

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 | null	no	-	-

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	-	-

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	-	-

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"	-

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	-

RevisionStatus

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

SessionStatus

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

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	-	-

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	-	-

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	yes	-	-
fail_code	string | null	yes	-	-
started_at	string (date-time)	yes	-	-
ended_at	string (date-time) | null	yes	-	-

ValidationError

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